CX_WEB_SERVICE_MANAGER::MorphITServerCommand
4.2.0
205954
Beschreibung:
Diese Methode bietet ClassiX eine generische Schnittstelle zur Kommunikation mit dem MorphIT-Server. Der MorphIT-Server definiert eine Reihe von Server-Befehlen, mit denen ClassiX das Verhalten des MorphIT-Servers steuern kann oder Informationen abfragen kann. Die Serverbefehle nutzen das Berechtigungssystem von MorphIT, um zu prüfen, ob ein bestimmter ClassiX-Prozess einen Server-Befehl ausführen darf oder nicht. Die für einen Befehl benötigten Berechtigungen sind bei der Beschreibung der Befehle mit aufgeführt.
Um einen Serverbefehl ausführen zu können, muss die ClassiX-Instanz logischer Weise am MorphIT-Server registriert sein. Sollte der Server auf einen Serverbefehl nicht innerhalb von 60 Sekunden antworten, wird der Aufruf mit einer Fehlermeldung abgebrochen. Diese Dauer lässt sich über die Umgebungsvariable CX_MORPHIT_COMMAND_TIMEOUT anpassen.
Serverbefehle
Der auszuführende Server-Befehl wird über das Feld command im Parameter-JSON angegeben. Je nach Befehl können/müssen weitere Parameter übergeben werden.
- morphit_version
- shutdown_classix
- request_binding
- launch_dedicated_classix
- set_path_map
- lock_launch
- unlock_launch
- send_webservice_request
- classix_status
- move_server
morphit_version
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string | "morphit_version" |
Dieser Befehl benötigt keine Berechtigungen und liefert Versionsinformationen über die MorphIT-Installation im folgenden Format:
Antwortformat:
Feld | Typ | Wert |
---|---|---|
type | string | "version" |
version | string | Die MorphIT Versionsnummer |
date | string | Das Build-Datum der MorphIT-Version im Format YYYY-MM-DD |
shutdown_classix
Berechtigungen:
- server_command.shutdown_classix
- server_command.shutdown_classix.role.(Rolle)
- server_command.shutdown_classix.webservice.(Name) (4.16.0)
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string | "shutdown_classix" |
instances | Array | Eine Liste mit Selektoren für die ClassiX-Instanzen, die beendet werden sollen. (Im nachfolgenden Absatz beschrieben) Die "self" und webservice-Selektoren werden 4.16.0 unterstützt. |
4.4.1 self |
boolean | Kann auf false gesetzt werden, um zu verhindern, dass die Instanz sich selbst beendet. Mit dem Selektor "all" und self=false kann eine Instanz beispielsweise alle anderen Instanzen beenden. Die Instanz wird auch dann nicht beendet, wenn sie explizit über ihre ID im Selektor angegeben wurde. |
reason | string | Ein optionaler Grund für das Beenden der Instanz. Dieser Grund wird von den beendeten Instanzen geloggt und den eventuell verbundenen MorphIT-Clients angezeigt. |
Mit diesem Befehl können einzelne oder mehrere ClassiX-Instanzen auf einmal beendet werden. In dem Feld reason kann optional eine Nachricht übergeben werden, die den verbundenen MorphIT-Clients angezeigt wird und von den beendeten ClassiX-Prozessen geloggt wird. Die Instanzen, die beendet werden sollen werden in einem JSON-Array im feld instances des Parameter-JSONs übergeben. Dabei gibt es folgende Möglichkeiten die Instanzen zu referenzieren:
[ "self", // The ClassiX instance issuing this command "all", // All connected ClassiX instances {"id":id}, // The ClassiX instance with the given id {"morphit":id}, // The ClassiX instance connected to the specific MorphIT instance {"pid":pid, "launcher":host}, // The ClassiX with the given pid and launcher hostname|ip {"roles":[role1,role2,...]}, // All ClassiX instances, which have ALL of the given roles {"webservice":name} // All ClassiX instances, which are assigned to the webserivce configuration with id='name' ]
Es ist kein Fehler, wenn ein Selektor keine Instanz referenziert, weil beispielsweise die ID nicht (mehr) gültig ist, der Selektor wird dann einfach übergangen. Eine Ausnahme ist die Angabe eines Hosts/IP auf der aktuell kein Launcher läuft für den Selektor: {"pid":pid, "launcher":host}. Dies wird als Fehler zurückgegeben.
Um ein ClassiX zu beenden, muss der aufrufende ClassiX-Prozess die Berechtigung server_command.shutdown_classix sowie server_command.shutdown_classix.role.(Rolle) für jede Rolle des zu beendenden Prozesses haben. Falls die zu beendende ClassiX-Instanz eine Webservice-Instanz ist, dann benötigt der Prozess zusätzlich die Berechtigung server_command.shutdown_classix.webservice.(Name) für die dazugehörige Webservice-Konfiguration (id). Hat der Prozess nicht ausreichend Berechtigungen, um alle angegebenen Prozesse zu beenden, erhält der aufrufende Prozess eine Fehlerantwort mit einer Liste der fehlenden Berechtigungen. Beispiel:
{ "type":"error", "error":"Missing permissions to shutdown classix instances", "permissions":["server_command.shutdown_classix.role.local"] }
Hat der aufrufende Prozess alle Berechtigungen, dann sendet der Server an alle erwähnten ClassiX-Prozesse einen shutdown-Befehl und sendet folgende Antwort, sobald alle Prozesse beendet wurden:
{ "type":"success", "affected_instances":[1,2,3,..] }
Das Feld affected_instances enthält dann ein Array mit den Ids der beendeten ClassiX Instanzen. Für den Fall, dass das aufrufende ClassiX sich über diesen Fall selbst beendet, sendet der Server die Antwort sofort und nicht erst nachdem sich alle Instanzen beendet haben.
Antwortformat
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
affected_instances | Array | Ein Array, das die ClassiX-Ids der beendeten ClassiX-Instanzen enthält. |
Codebeispiel:
Var(json) CreateTransObject(CX_JSON_OBJECT) -> json "shutdown_classix" json Put(command) "Shutdown command test" json Put(reason) // shutdown all instances local to the server "local" json Put(instances[0].roles[0]) json GetManager(WEB_SERVICE) Call(MorphITServerCommand)
request_binding
Berechtigungen:
- server_command.request_binding
- server_command.request_binding.grant_role.(Rolle)
- server_command.request_binding.asset_route.default
- server_command.request_binding.asset_route.(Route)
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string | "request_binding" |
url | string | Ein optionale relative oder absolute URL, auf die ein verbundener MorphIT-Client im neuen Tab wechseln soll. Falls kein Client verbunden ist, dann hat dieser Parameter keinen Effekt. Beim statischen Login über einen Webservice kann der gleiche Effekt mit dem url-Feld der login/dynamic-Antwort erzielt werden. |
roles | Array |
Eine Liste von Rollen, die dem zu startenden ClassiX-Prozess vom MorphIT-Server zugewiesen werden sollen, sobald sich dieser mit dem Server verbindet. Für jede hier angegebene Rolle muss der ausführende Prozess die Berechtigung haben, um diese Rolle zu vergeben (server_command.request_binding.grant_role.(Rolle)). Systemrollen dürfen hierbei nicht vergeben werden. Achtung: Wenn es Rollen gibt, die durch die Verwendung von blacklist oder overwrites die Berechtigungen der Systemrollen nur einschränken, dann kann ein ClassiX-Prozess seine Rechte dadurch ausbauen, dass er eine andere ClassiX-Instanz ohne Rollen startet. Die andere Instanz hätte dann mehr rechte, als die startende Instanz. So eine Konfiguration stellt ein Sicherheitsrisiko dar und Rollen sollten entweder nicht so definiert werden, dass sie Rechte einschränken oder die Berechtigung server_command.request_binding muss durch so eine Rolle ebenfalls unterbunden werden. |
asset_route 4.4.0 |
Objekt |
Mit diesem Parameter kann die Pfadkonfiguration der zu startenden ClassiX-Instanz definiert werden. Die ClassiX-Instanz erhält die angegebene Pfadkonfiguration nach der Registrierung beim Server. Die Pfadkonfiguration wird angegeben als Objekt der Form Query-Parameter -> Wert. Beispiel: {"client":"classix", "product":"gestin"}. Dieser Parameter ist optional und falls er nicht angegeben wird, erhält das gestartete ClassiX die gleiche Pfadkonfiguration, wie das startende ClassiX. Hierfür sind keine Berechtigungen notwendig. Dieser Parameter ist nicht erlaubt, wenn cloud.enabled=false gesetzt ist. |
dialog_message 4.8.4 |
string | Über diesen Parameter kann der Dialog-Text überschrieben werden, der im MorphIT-Client dargestellt und vom Nutzer bestätigt werden muss, damit MorphIT im neuen Tab die Verbindung zum neuen ClassiX-Prozess aufbaut. |
queue_message 4.8.4 |
string | Über diesen Parameter kann der Text überschrieben werden, der im neuen MorphiT-Browser-Tab angezeigt wird, während auf die neue ClassiX-Instanz gewartet wird. Der Standard-Text lautet in deutscher Sprache:
"Warte auf freie ClassiX-Instanz... Position in Warteschlange {{position}} von {{total}}" |
Dieser Server-Befehl ist der äquivalente Serverbefehl zu RequestMorphITBinding und ist dort dokumentiert. Im Gegensatz zu RequestMorphITBinding wertet der Serverbefehl die Antwort nicht aus und setzt damit auch die Umgebungsvariable CX_MORPHIT_NONCE nicht automatisch.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "requested_binding" |
nonce | string | Der Nonce-Wert, der dem zu startenden ClassiX übergeben werden muss, damit der Server die Instanz erkennt und mit dem korrekten MorphIT-Client verbinden kann. |
endpoint | string | Der zum Nonce-Wert gehörende MorphIT-Endpunkt an den sich der MorphIT-Client verbinden muss, um mit dem frisch gestarteten ClassiX-Prozess verbunden zu werden. |
launch_dedicated_classix
Berechtigungen:
- server_command.launch_dedicated_classix
- server_command.launch_dedicated_classix.ip.(IP|Hostname)
- server_command.launch_dedicated_classix.at.self
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string | "launch_dedicated_classix" |
host | string | Der Host auf dem der ClassiX-Prozess gestartet werden soll (IP oder Hostname). Die IP-Adresse ist relativ zum MorphIT-Server und unter dieser IP-Adresse muss sich beim MorphIT-Server ein Launcher angemeldet haben, damit der Befehl erfolgreich ist. Per @self kann die Maschine des aufrufenden Prozesses referenziert werden. |
cmd | string | Der Befehl, der auf dem angegebenen Launcher ausgeführt werden soll |
nonce | string | Der Nonce-Wert aus request_binding, der in die Umgebungsvariable CX_MORPHIT_NONCE des zu startenden Prozesses gesetzt wird, damit der MorphIT-Server den ClassiX-Prozess korrekt erkennen kann. |
config.cwd | string | Das Arbeitsverzeichnis, in welchem cmd ausgeführt werden soll. Ist dieser Wert nicht gesetzt, dann verwendet der Launcher den Wert aus ws.launcher.launch.cwd aus seiner config.js. |
config.env | Objekt | Ein Objekt, welches die zu setzenden Umgebungsvariablen für die Ausführung von cmd definiert. (Default: {}) |
Dieser Server-Befehl ist der äquivalente Serverbefehl zu LaunchDedicatedClassiX und ist dort dokumentiert. Ein Launcher ist beim Server meist unter mehreren IP-Adressen und einem Hostnamen bekannt. Der aufrufende Prozess muss für mindestens eine der IP-Adressen oder den Hostnamen (in Kleinbuchstaben) die Berechtigung server_command.launch_dedicated_classix.ip.(IP|Hostname) haben, um dort einen Prozess starten zu dürfen. Die Berechtigung server_command.launch_dedicated_classix.at.self erlaubt das Starten von Prozessen auf der Maschine des aufrufenden Prozesses (siehe auch @self), ohne dass eine Berechtigung für den Hostnamen oder die IP-Adresse vorhanden sein muss.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "dedicated_launch_response" |
pid | integer | Die Prozess-ID des gestarteten Prozesses |
set_path_map
4.4.0
Berechtigungen:
- server_command.set_path_map
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string | "set_path_map" |
paths | Objekt | Eine dynamische Pfadkonfiguration, die gesetzt werden soll. |
Dieser Befehl setzt (überschreibt) die aktuelle dynamische Pfadkonfiguration des Servers. Die neue Konfiguration wird sofort übernommen. Dieser Befehl kann nur dann ausgeführt werden, wenn in der config.js des Servers cloud.enabled=true gesetzt ist.
Codebeispiel:
Var(json) CreateTransObject(CX_JSON_OBJECT) -> json "set_path_map" json Put(command) "Y:\\classix\\Evaluate\\WebWidgets" json Put(paths.classix.evaluate.public.widgets.path[0]) "Y:\\classix\\main\\WebWidgets" json Put(paths.classix.evaluate.public.widgets.path[1]) "Y:\\classix\\Evaluate\\bmp" json Put(paths.classix.evaluate.private.bmp.path) "Y:\\classix\\Evaluate\\icons" json Put(paths.classix.evaluate.private.icons.path) "Y:\\classix\\Evaluate\\projects\\data\\assets" json Put(paths.classix.evaluate.private.assets.path) json GetManager(WEB_SERVICE) Call(MorphITServerCommand)
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
lock_launch
4.4.1
Berechtigungen:
- server_command.lock_launch
- server_command.lock_launch.role.(Rolle)
- server_command.lock_launch.global
- server_command.lock_launch.persistent
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string | "lock_launch" |
roles | Array | Optionale Liste der Rollen für die ein Starten verhindert werden soll. Für jede hier aufgeführte Rolle benötigt der Prozess die Berechtigung server_command.lock_launch.role.Role. Falls die Liste leer ist oder das Feld nicht gesetzt ist, benötigt der Prozess die Berechtigung: server_command.lock_launch.global. Werden hier Systemrollen angegeben, dann hat dies keinen Einfluss darauf, ob Instanzen mit diesen Rollen gestartet werden können. |
timeout | int | Der Timeout in Millisekunden, nach dem das Lock automatisch wieder aufgehoben wird. |
persistent | boolean | Kann auf true gesetzt werden, damit das Lock auch dann bestehen bleibt, wenn dieser ClassiX-Prozess die Verbindung zum MorphIT-Server trennt. Normalerweise werden alle gesetzten Locks aufgehoben, sobald der Prozess die Verbindung zum Server trennt. Hierfür wird die Berechtigung server_command.lock_launch.persistent benötigt. |
Dieser Befehl setzt ein Launch-Lock im Server, mit dem verhindert werden kann, dass der Server den Start von bestimmten ClassiX-Instanzen durchführt/zulässt. Ein Lock ohne oder mit leerem roles-Parameter wird interpretiert als globales Lock. Hiermit werden alle ClassiX-Starts durch den Server unterbunden (request_binding & vorgestartete Instanzen). Falls Rollen im roles-Parameter gesetzt sind, dann lehnt der Server alle request_binding-Aufrufe mit einem Fehler ab, die eine der im Lock angegebenen Rollen enthalten. Sollte ein globales Lock gesetzt sein, dann wartet der Server mit dem Starten von neuen vorgestarteten ClassiX-Instanzen solange, bis das letzte globale Lock deaktiviert wurde.
Eine ClassiX-Instanz kann beliebig viele Locks gleichzeitig setzen.
Jedes Lock kann jederzeit mit dem Serverbefehl unlock_launch wieder aufgehoben werden.
Codebeispiel:
Var(json) CreateTransObject(CX_JSON_OBJECT) -> json "lock_launch" json Put(command) "client.classix" json Put(roles[0]) // prevent request_binding with roles = client.classix 10000 "timeout" json Call(PutTyped) // for 10s json GetManager(WEB_SERVICE) Call(MorphITServerCommand)
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
unlock_launch
4.4.1
Berechtigungen:
- server_command.unlock_launch
- server_command.unlock_launch.issuer_role.(Rolle)
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"unlock_launch" |
issuer_roles | Array | Eine Liste von Rollen, mit denen die aufzuhebenden Locks ausgewählt werden. Hierbei werden die Rollen des Prozesses aufgeführt, der das Lock angelegt hat. Alle Locks, deren Ersteller zumindest eine der hier angegebenen Rollen hat, werden damit aufgehoben. |
issuer_id | string |
In diesem Feld kann optional die ClassiX-Id des Prozesses angegeben werden, dessen Locks aufgehoben werden sollen. Falls dieses Feld gesetzt ist, wird issuer_roles ignoriert. Hier kann der Spezialwert @self gesetzt werden, um sich nur auf die Locks zu beziehen, die von diesem Prozess gesetzt wurden. |
roles | Array | Analog zu lock_launch werden hier die durch das Lock gesperrten Rollen angegeben. Hiermit werden nur die Locks ausgewählt, die genau diese Rollen sperren. |
Dieser Befehl dient dazu die Locks, die durch lock_launch gesetzt wurden wieder aufzuheben. Die Parameter issuer_roles, issuer_id und roles dienen als Lock-Selektoren, mit denen man die Menge der aufzuhebenden Locks einschränken kann. Ist keiner der Parameter gesetzt, dann werden alle im Server gesetzten Locks aufgehoben. Es ist nicht möglich, durch die Angabe von roles die aufzuhebenden Locks nur auf globale Locks einzuschränken.
Jedes Lock, das per lock_launch gesetzt wurde, kennt die Rollen des Prozesses, der das Lock angelegt hat. Um ein Lock wieder zu entfernen, muss der Prozess für jede dieser Rollen die Berechtigung server_command.unlock_launch.issuer_role.Rolle haben. Dies gilt auch für (issuer_id="@self").
Codebeispiel:
Var(json) CreateTransObject(CX_JSON_OBJECT) -> json "unlock_launch" json Put(command) "@self" json Put(issuer_id) // release all locks, which have been set by this process json GetManager(WEB_SERVICE) Call(MorphITServerCommand)
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
locks_released | int | Die Anzah der Locks, die mit diesem Befehl aufgehoben wurden. |
send_webservice_request
4.16.0
Berechtigungen:
- server_command.send_webservice_request
- server_command.send_webservice_request.path.(Pfad-Id)
- server_command.send_webservice_request.method.(Methode)
- server_command.send_webservice_request.to.webservice.(Id)
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"send_webservice_request" |
parameters.path | string | Die Anfrage-URL beginnend mit "/". Dieser Pfad darf Query-Parameter enthalten. Sonderzeichen müssen entsprechend korrekt URL-kodiert sein. Das erste Pfad-Element (bis zum ersten "/" oder "?") in Kleinbuchstaben wird hier als Pfad-Id bezeichnet und der ClassiX-Prozess benötigt die Berechtigung: server_command.send_webservice_request.path.(Pfad-Id) um Webservice-Anfragen an diesen Pfad zu senden. |
parameters.method | string | Die HTTP-Methode der Anfrage. Der Default-Wert ist hier "POST". Der ClassiX-Prozess benötigt die Berechtigung: server_command.send_webservice_request.method.(Methode), um eine Webservice-Anfrage mit der angegebenen Methode zu senden, wobei die Methode in den Berechtigungen komplett kleingeschrieben ist. |
parameters.headers | Objekt | Ein optionales Objekt, in welchem die HTTP-Header der Anfrage übergeben werden können. |
json | beliebig | Falls die Anfrage ihren HTTP-Body im JSON-Format übergeben soll, dann der JSON-Datentyp einfach in dieses Feld geschrieben werden. Der Content-Type-Header wird bei der Anfrage dadurch automatisch auf "application/json" gesetzt. |
base64 | string | Falls die Anfrage als HTTP-Body kein JSON enthält, dann muss der Anfrage-Body Base64-kodiert in dieses Feld geschrieben werden. Die Base64-Kodierung ermöglicht auch das Übertragen von Binärdateien. |
instance.webservice | string |
Das instance-Feld ist optional und erlaubt im Gegensatz zu shutdown_classix nur einen Eintrag. Hierüber kann die Webservice-Konfiguration festgelegt werden, welche die Anfrage bearbeiten soll. Dies funktioniert auch dann, wenn angegebene Konfiguration für den Pfad/die Methode der Anfrage gar nicht zuständig ist und kann verwendet werden, um interne Steuernachrichten/Abfragen an die Webservice-Instanzen zu senden, die von Außen nicht zugänglich sein sollen. Falls dieses Feld nicht gesetzt ist oder einen Leerstring enthält, dann wird die Konfiguration gewählt, die für den Pfad und die Methode der Anfrage zuständig ist. In beiden Fällen muss der ClassiX-Prozess die Berechtigung server_command.send_webservice_request.to.webservice.(Id) besitzen, um eine Webservice-Nachricht an diesen Webservice zu senden. |
instance.id | string |
Alternativ zur Angabe der Webservice-Konfiguration, kann auch die ClassiX-Id (nicht die Prozess-ID, siehe classix_status) des Prozesses angegeben werden, welcher die Anfrage behandeln soll. Dies funktioniert jedoch nur, wenn der ClassiX-Prozess auch als Webservice-Instanz am MorphIT-Server angemeldet ist. Auch hierüber können Anfragen mit Methoden/Pfaden an die Instanz gesendet werden, die in der Konfiguration nicht aufgeführt und von Außen nicht erreichbar sind. Achtung: Eine Webservice-Instanz kann keine Webservice-Nachricht an sich selbst senden. |
Dieser Befehl bietet jeder ClassiX-Instanz, die mit einem MorphIT-Server verbunden ist (und über die entsprechenden Berechtigungen verfügt) die Möglichkeit, Webservice-Anfragen direkt and die Webservice-Instanzen des MorphIT-Servers zu senden, ohne hierfür eine HTTP-Verbindung mit dem externen HTTP-Port des MorphIT-Servers aufbauen zu müssen.
Des weiteren können per instance.webservice Webservice-Anfragen gesendet werden, die von außen gar nicht erreichbar sind, was für interne Steuernachrichten/Abfragen nützlich sein kann.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
response.type | string | "webservice" |
response.parameters.headers | Objekt | Die HTTP-Header der Antwort als JSON-Objekt |
response.parameters.status | int | Der HTTP-Status-Code der Antwort. |
response.json | beliebig |
Falls der Webservice mit einem JSON Datentypen im HTTP-Body geantwortet hat |
response.base64 | string | Alle anderen HTTP-Body-Werte werden als Base64-kodierter String in dieses Feld geschrieben. |
classix_status
4.16.0
Berechtigungen:
- server_command.classix_status
- server_command.classix_status.role.(Rolle)
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"classix_status" |
instances | Array |
Ein Array von Selektoren, die definieren zu welchen ClassiX-Instanzen der Status abgefragt werden soll. Hier werden die gleichen Selektoren unterstützt wie bei shutdown_classix. |
Dieser Befehl bietet jeder ClassiX-Instanz, die mit einem MorphIT-Server verbunden ist (und über die entsprechenden Berechtigungen verfügt) die Möglichkeit, status-Informationen über sich selbst oder andere ClassiX-Instanzen abzufragen, die nur der MorphIT-Server kennt, wie der Zeitpunkt der letzten Nachricht oder die zugewiesenen Rollen und welche ClassiX-Instanzen welcher Webservice-Konfiguration zugewiesen sind.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
status | Array | Ein Array mit Status-Objekten. Jedes-Status-Objekt repräsentiert eine ClassiX-Instanz |
status[].id | string|int | Die ClassiX-Id des Prozesses. |
status[].ip | string | Die (lokale) IP-Adresse des ClassiX-Prozesses (aus Sicht des MorphIT-Servers). |
status[].pid | int | Die Prozess-Id des ClassiX-Prozesses. |
status[].dllVersion | string | Die volle Dll-Version des ClassiX-Prozesses. |
status[].appswhVersion | string | Die AppsWH-Version (falls bekannt), ansonsten ein Leerstring. |
status[].mode | string | "background" für durch Launcher gestartete ClassiX-Instanzen. "interactive" für interaktive/manuell gestartete ClassiX-Instanzen. |
status[].registerTime | string | Der Zeitpunkt im ISO-Format, wann sich ClassiX am MorphIT-Server registriert/angemeldet hat. Beispiel: "2023-07-28T07:27:12.298Z" |
status[].launcher_ip | string | Falls der Prozess über einen Launcher gestartet wurde, dann enthält dieses Feld die IP-Adresse dieses Launchers. |
status[].lastMessage | string | Falls der Prozess eine Webservice-Nachricht oder eine Nachricht vom MorphIT-Client erhalten hat, dann enthält dieses Feld den Zeitpunkt der letzten Nachricht, die erhalten wurde im ISO-Format. |
status[].webservice | bool | true, falls diese ClassiX-Instanz als Webservice-Instanz zugewiesen ist. |
status[].webservice_id | string | Falls diese ClassiX-Instanz eine Webservice-Instanz ist, dann enhtält dieses Feld die Id der Webservice-Konfiguration, welcher diese ClassiX-Instanz zugewiesen ist. |
status[].morphit.id | string|int | Falls die ClassiX-Instanz mit einem MorphIT-Client verbunden ist, dann enthält dieses Feld die Id dieses MorphIT-Clients. |
status[].morphit.ip | string | Falls die ClassiX-Instanz mit einem MorphIT-Client verbunden ist, dann enthält dieses Feld die IP-Adresse dieses MorphIT-Clients aus Sicht des MorphIT-Servers. |
status[].webwidget.widgets | int | Falls native WebWidgets dieser ClassiX-Instanz geöffnet sind, dann enthält dieses Feld die Anzahl der geöffneten WebWidgets. |
status[].assetRoute | Objekt | 4.17.0 Falls der Server im Cloud-Modus läuft (cloud.enabled=true), dann entspricht dieses Objekt dem in request_binding gesetzten asset_route Parameter. Instanzen ohne Asset-Route enthalten hier ein leeres Objekt. |
status[].roles | Array | Ein Array von strings mit den Namen der Rollen, die dieser ClassiX-Instanz zugewiesen sind. |
status[].dedicated | bool | true, falls diese ClassiX-Instanz eine dediziert gestartete ClassiX-Instanz ist. |
move_server
4.17.0
Berechtigungen:
- server_command.move_server
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string |
Der auszuführende Schritt ("init", "move_ls", "ws_status", "move_ws", "abort", "commit"). Die einzelnen Schritte erwarten unterschiedliche Parameter und sind weiter unten beschrieben. |
Dieser Befehl ermöglicht es, den MorphIT-Server im laufenden Betrieb ohne Unterbrechung auf eine andere Maschine zu verschieben. Hierzu bauen beide Server eine bidirektionale Verbindung miteinander auf über welche die Server ihren Zustand untereinander austauschen und die Aufgaben schrittweise übertragen.
Der init-Schritt ist der einzige Befehl, der von einer ClassiX-Instanz ausgeführt werden muss, die mit dem Quell-Server verbunden ist. Alle nachfolgenden Schritte können auch von einer ClassiX-Instanz auf dem Ziel-Server ausgeführt werden.
Hauptartikel zum Servermove-Feature von MorphIT.
Schritte:
init-Step
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "init" |
host | string | Der Hostname des Zielservers (Ein MorphIT-Server muss dort bereits laufen) |
port | int | Der Port der Admin-Konsole des Zielservers (falls abweichend vom lokalen Server) |
endpoint | string | Der Endpunkt der Admin-Konsole des Zielservers (falls abweichend vom lokalen Server) |
ssl | bool | Ist SSL (TLS) für die Admin-Konsole des Zielservers aktiv (falls abweichend vom lokalen Server) |
rollback_ws | Objekt |
Ein optionaler Webservice-Request im gleichen Format wie in send_webservice_request beschrieben, der auf dem Ausgangsserver ausgelöst wird, falls aufgrund eines Fehlers ein Rollback durchgeführt werden musste. |
Der init-Schritt wird auf dem aktuell (produktiv laufenden) Quellserver ausgeführt und dieser baut eine bidirektionale move_server-Verbindung mit dem angegebenen Zielserver auf. Hierzu wird zunächst eine Admin-Verbindung zu dem Zielserver aufgebaut und der Zielserver hierüber dazu aufgefordert eine Verbindung zu einem neuen move_server-Endpunkt (über einen Nonce-Wert abgesichert) aufzubauen.
Damit die Verbindung aufgebaut werden kann, müssen folgende Konfigurationseinträge auf beiden Servern gesetzt sein:
- ws.move_server.enabled=true
- ws.admin.enabled=true
- ws.admin.allowed_ips - muss auf dem Zielserver die IP des Quellservers enthalten.
Während die move_server-Verbindung aufgebaut wird, werden auf dem Zielserver alle ClassiX-Instanzen beendet, alle MorphIT-Verbindungen getrennt und alle Webservice-Konfigurationen deaktiviert. Alle Änderungen and der Server-Konfiguration, die während des Server-Moves durchgeführt werden, werden beim Abbruch der move_server-Verbindung auf beiden Servern automatisch wieder zurückgerollt und nach einer geringen Unterbrechung sollte der Quellserver wieder wie vor der angefangenen Umstellung verfügbar sein. Während eines Rollbacks (auch bei abort) werden alle auf dem Zielserver gestarteten ClassiX-Instanzen wieder beendet.
Sobald dieser Befehl erfolgreich ausgeführt wurde, arbeitet der Quellserver wie bisher, nur dass nun beim dedizierten Start von ClassiX-Instanzen die Launcher des Zielservers ebenfalls zur Verfügung stehen und ClassiX-Prozesse auch dort gestartet werden können.
Die ClassiX-Prozesse verbinden sich zu dem MorphIT-Server, der zu dem Launcher gehört, der den ClassiX-Prozess gestartet hat.
MorphIT-Clients können sich mit einem beliebigen MorphIT-Server verbinden ihre Verbindung wird bei Bedarf durch die move_server-Verbindung zum anderen Server und dem dortigen ClassiX-Prozess geleitet.
Falls beide Server über das Internet erreichbar sind, dann kann ab jetzt der DNS-Eintrag vom Quell-Servers auf den Ziel-Server geändert werden.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
move_ls-Step
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "move_ls" |
to_source | bool | Falls true, dann wird die Launch-Strategie zum Quellserver verschoben, ansonsten zum Zielserver (default). |
Mit diesem Schritt wird die Launch-Strategie - also das automatische Starten von Instanzen - auf den angegebenen Server verschoben und bereits vorgestartete und noch unbenutzte ClassiX-Instanzen beendet. Während einer bestehenden move_server-Verbindung ist die Launch-Strategie immer auf genau einem der beiden Server aktiv und MorphIT-Clients ohne statischen Login werden mit dem Server mit der aktiven Launch-Strategie verbunden.
Da Webservice-Instanzen ohne Angabe eines Startbefehls über die Launch-Strategie gestartet werden, sollte vor dem Verschieben solcher Webservice-Instanzen zunächst immer die Launch-Strategie auf den entsprechenden Server verschoben werden.
Falls der Befehl wiederholt wird und der Launch-Strategie auf diesem Server bereits aktiv ist, dann tut dieser Befehl nichts.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
cx_status
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "cx_status" |
Dieser Schritt liefert den Serverübergreienden Status der verbundenen ClassiX-Instanzen analog zum Befehl classix_status, mit dem Unterschied, dass es keinen Selektor gibt und immer alle Instanzen zurückgegeben werden und dass die Instanzen beider Server zurückgegeben werden.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
source | Array | Ein Array mit Objekten, die alle Instanzen auf dem Quellserver repräsentieren. Die Objekte haben den gleichen Aufbau, wie in classix_status beschrieben. |
target | Array | Ein Array mit Objekten, die alle Instanzen auf dem Zielserver repräsentieren. Die Objekte haben den gleichen Aufbau, wie in classix_status beschrieben. |
ws_status
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "ws_status" |
Dieser Befehl dient als Hilfestellung für das Verschieben von Webservice-Instanzen und liefert eine Übersicht, welche Webservice-Konfiguration auf welchem Server aktiv ist. Bevor ein Servermove abgeschlossen werden kann, müssen alle Webservices auf den Zielserver verschoben werden.
Dieser Schritt entfällt, falls Webservices in der Server-Konfiguration deaktiviert sind.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
source | Objekt | Status der Webservices auf dem Quellserver |
source.enabled | Array | Liste mit Config-Ids (strings) der aktivierten Webservice-Konfigurationen auf dem Quellserver |
source.disabled | Array | Liste mit Config-Ids (strings) der deaktivierten Webservice-Konfigurationen auf dem Quellserver |
target | Objekt | Status der Webservices auf dem Zielserver |
target.enabled | Array | Liste mit Config-Ids (strings) der aktivierten Webservice-Konfigurationen auf dem Zielserver |
target.disabled | Array | Liste mit Config-Ids (strings) der deaktivierten Webservice-Konfigurationen auf dem Zielserver |
move_ws-Step
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "move_ws" |
config_ids | Array | Ein Array von Config-Ids (strings) der Webservice-Konfigurationen, die auf dem Quellserver deaktiviert und auf dem Zielserver aktiviert werden sollen. |
to_source | bool | Falls true, dann werden die angegebenen Webservice-Konfigurationen auf dem Zielserver deaktiviert und auf dem Quellserver aktiviert. |
Dieser Schritt verschiebt die angegebenen Webservice-Konfigurationen auf den angegebenen Zielserver, indem die Konfigurationen auf dem Zielserver aktiviert und Webservice-Instanzen gestartet werden. Sobald die Webservices auf dem Zielserver bereit sind, werden die Webservice-Konfigurationen auf dem Quellserver deaktiviert (und die ClassiX-Instanzen beendet) und alle Webservice-Anfragen für diese Konfigurationen auf den Zielserver umgeleitet. Diese Vorgehensweise ermöglicht ein unterbrechungsfreies Verschieben der Webservice-Konfiguration.
Falls to_source auf true gesetzt ist, dann werden die Instanzen in die umgekehrte Richtung verschoben.
Die bei move_ws angegebenen Konfigurationen müssen nicht zwangsläufig auf beiden Servern vorhanden sein. Existiert eine Konfiguration nur auf dem Quell-Server, dann wird sie dort nur deaktiviert. Existiert eine Konfiguration nur auf dem Zielserver, dann wird sie dort nur aktiviert.
Die Anfrage kehrt erst zurück, wenn die angegebenen Instanzen erfolgreich verschoben wurden. Da hierfür pro Konfiguration mindestens eine ClassiX-Instanz gestartet werden muss, wird empfohlen die Konfigurationen einzeln zu verschieben, oder CX_MORPHIT_COMMAND_TIMEOUT hochzusetzen, da der Aufruf ansonsten mit einem Timeout fehlschlagen kann und man nicht erfährt, ob und wann das Verschieben erfolgreich war.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
abort-Step
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "abort" |
Dieser Befehl bricht einen laufenden Server-Move ab, indem die move_server-Verbindung zwischen den beiden MorphIT-Servern einfach geschlossen wird. Dieser Schritt kann nach dem init-Schritt und VOR dem commit-Schritt ausgeführt werden. Beide MorphIT-Server führen im Anschluss einen automatischen Rollback der bisherigen Schritte durch.
Da dieser Befehl die Verbindung sofort schließt, kann es hierdurch zu einer Unterbrechung für die Clients kommen, falls ein Großteil der Funktionalität bereits auf den Ziel-Server verschoben wurde. Um die Unterbrechnung zu vermeiden, sollten alle bereits durchgeführten Schritte nach Möglichkeit vorher manuell zurückgerollt werden.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
commit-Step
Anfrageformat:
Feld | Typ | Beschreibung |
---|---|---|
command | string |
"move_server" |
step | string | "commit" |
Dieser Befehl stellt den letzten Schritt eines Server-Moves dar und prüft zunächste, ob folgende Vorbedingungen erfüllt sind:
- Die Launch-Strategie wurde auf den Zielserver verschoben
- Alle Webservice-Konfigurationen des Quellservers sind deaktiviert und alle Webservice-Konfigurationen des Zielservers sind aktiviert.
Falls eine der Bedingungen nicht erfüllt ist, bricht der Befehl mit einer entsprechenden Fehlermeldung ab.
Ansonsten wird auf beiden Servern vermerkt, dass ab sofort bei einem Abbruch der move_server-Verbindung kein Rollback der Konfiguration mehr durchgeführt wird, stattdessen schaltet der Zielserver dann in den vollen Echtbetrieb um.
Der Quellserver wartet bis die letzte auf dem Server aktive (potenziell weitergeleitete) MorphIT/ClassiX-Verbindung geschlossen wurde, schließt dann die move_server-Verbindung und wechselt in den Wartungsmodus. Der Server-Wechsel ist damit abgeschlossen.
Antwortformat:
Feld | Typ | Beschreibung |
---|---|---|
type | string | "success" |
Liste aller Berechtigungen:
name | Berechtigung |
---|---|
server_command.shutdown_classix | Serverbefehl shutdown_classix ausführen. |
server_command.shutdown_classix.webservice.(Name) | Ein ClassiX welches dieser Webservice-Konfiguration zugewiesen ist per shutdown_classix beenden. |
server_command.shutdown_classix.role.(Rolle) |
Ein ClassiX mit dieser Rolle per shutdown_classix beenden. |
server_command.request_binding | Serverbefehl request_binding ausführen. |
server_command.request_binding.grant_role.(Rolle) | In request_binding die angegebene Rolle dem neuen ClassiX zuweisen. |
server_command.launch_dedicated_classix |
Serverbefehl launch_dedicated_classix ausführen. |
server_command.launch_dedicated_classix.ip.(ip|hostname) | Ein ClassiX per launch_dedicated_classix auf dem angegebenen Launcher starten. Der hostname sollte in Kleinbuchstaben geschrieben werden. |
server_command.launch_dedicated_classix.at.self | Ein ClassiX per launch_dedicated_classix auf der gleichen Maschine wie der aufrufende ClassiX-Prozess zu starten. |
server_command.set_path_map | Serverbefehl set_path_map ausführen. |
server_command.lock_launch | Serverbefehl lock_launch ausführen. |
server_command.lock_launch.role.(Rolle) | Die angegebene Rolle darf durch ein Launch-Lock gesperrt werden. |
server_command.lock_launch.global | Der Prozess darf ein globales Launch-Lock setzen und alle ClassiX-Starts sperren. |
server_command.lock_launch.persistent | Der Prozess darf ein persistentes Lock setzen. |
server_command.unlock_launch | Serverbefehl unlock_launch ausführen. |
server_command.unlock_launch.issuer_role.(Rolle) | Locks, die von einem Prozess mit dieser Rolle gesetzt wurden dürfen aufgehoben werden. |
server_command.send_webservice_request | Serverbefehl send_webservice_request ausführen. |
server_command.send_webservice_request.path.(Pfad-Id) | Webservice-Anfragen mit den angegebenen Pfad (alles hinter "/" und vor dem ersten "/" oder "?", kleingeschrieben) dürfen per send_webservice_request gesendet werden. |
server_command.send_webservice_request.method.(Methode) | Webservice-Anfragen mit der angegebenen HTTP-Methode (kleingeschrieben) dürfen per send_webservice_request gesendet werden. |
server_command.send_webservice_request.to.webservice.(Id) | Werbservice-Anfragen dürfen an Webservice-Instanzen mit der angegebenen Konfigurations-Id per send_webservice_request gesendet werden. |
server_command.classix_status | Serverbefehl classix_status ausführen. |
server_command.classix_status.role.(Rolle) | Der classix_status darf für die Instanz mit der angegebenen Rolle abgefragt werden. |
server_command.move_server | Serverbefehl move_server ausführen. |
Stack | Position | Objekttyp | Kurzbeschreibung |
---|---|---|---|
Stack(In) | Top | CX_WEB_SERIVCE_MANAGER | Der Webservice-Manager |
Top-1 | CX_JSON_OBJECT | Befehlsobjekt | |
Stack(Out) | Top | CX_JSON_OBJECT | Die Antwort des Servers als JSON-Objekt |