Online-Hilfe icom Data Suite

Kommandozeilenschnittstelle (CLI)

Die Applikation verfügt über eine Kommandozeilen-Schnittstelle (CLI, Command Line Interface) zur Konfiguration aus dem lokalen Netz oder aus der Ferne mit Telnet oder SSH.

Über die CLI wird zeilenweise ein Parameter nach dem anderen eingegeben und im geöffneten Profil gespeichert. Die Änderungen am Profil werden damit im laufenden Profil noch nicht wirksam. Das Profil muss noch aktiviert, d.h. zum laufenden Profil werden, damit die Änderungen der Konfiguration wirksam werden.

Aktivieren der CLI

Bevor ein Zugriff auf die Applikation mit Telnet oder SSH möglich ist, muss dies im Menü Administration auf der Seite CLI entsprechend konfiguriert werden. Dazu muss der Zugang über Telnet oder SSH aktiviert werden und bei aktiver Firewall im Router eine entsprechende Ausnahmeregel vorhanden und aktiv sein.

Syntax

Die Syntax eines Parameters setzt sich aus den Sektionen sowie dem Parameter, jeweils getrennt durch einen Punkt zusammen. Die Sektionen entsprechen der Menüstruktur im Web-Interface. Der Parameter Kommandozeile via SSH aktivieren im Menü Administration auf der Seite CLI hat beispielsweise folgende Syntax:
> administration.cli.ssh_active
Dabei entsprechen die beiden Sektionen vor dem Parameter dem Menü und der Seite im Web-Interface. Das hier dargestellte Zeichen > stellt den Befehls-Prompt dar und ist nicht Bestandteil des Befehls.

Die verfügbaren Sektionen und Parameter hängen von der Version der Applikation ab. Mit Hilfe der Autovervollständigung durch die Tabulator-Taste können diese bequem angezeigt werden. Ein Druck auf die Tabulator-Taste zeigt alle verfügbaren Sektionen der ersten Ebene an (entspricht den Menüs im Web-Interface). Die Eingabe des/der ersten Anfangsbuchstaben einer Sektion gefolgt von der Tabulator-Taste vervollständigt die Sektion und ein weiterer Druck auf die Tabulator-Taste zeigt alle verfügbaren Sektionen der nächsten Ebene an (entspricht den Seiten dieses Menüs im Web-Interface). Ein weiterer Druck auf die Tabulator-Taste zeigt mögliche weitere Sektionen oder die verfügbaren Parameter an. Bei Listen wird automatisch die geöffnete eckige Klammer ([) ausgegeben. Wenn diese durch einen Punkt ersetzt wird, gibt ein weiterer Druck auf die Tabulator-Taste die verfügbaren Listen-Funktionen aus.
Siehe auch dieses Beispiel für die Vorgehensweise zum Ermitteln der Befehls-Syntax

Zeilen, die mit einer Raute # beginnen, werden ignoriert und können als Kommentare verwendet werden.

Aktivieren eines Profils

Wird ein Profil mit der CLI wie im Folgenden beschrieben verändert, werden die Änderungen erst wirksam, wenn das Profil aktiviert wird, d.h. zum laufenden Profil wird.
Beispiel für das Aktivieren des geöffneten Profils:
> administration.profiles.activate
>
Beispiel für das Aktivieren des Profils "Profile_2":
> administration.profiles.activate=Profile_2
>

Auslesen von Parameter-Werten

Der aktuelle Wert eines Parameters wird durch Eingabe des Parameters gefolgt von der Eingabe-Taste angezeigt. Wird nur die übergeordnete Sektion angegeben, so werden alle darunterliegenden Parameter ausgegeben. Beispiel:
> administration.cli.ssh_active
1
> administration.time
administration.time.timezone=Regensburg

Setzen von Parameter-Werten

Ein neuer Wert wird einem Parameter durch Eingabe des Parameters gefolgt von einem Gleichheitszeichen und dem neuen Wert übergeben. Beispiel:
> administration.cli.telnet_active=1
>

Bearbeiten von Listen

Neben festen Parametern verfügt die Applikation auch über endlos erweiterbare Listen, wie beispielsweise die der angelegten Benutzer. Die einzelnen Einträge einer Liste werden der Reihe nach durchnummeriert und sind über diese Positionsnummer ansprechbar. Beispielsweise wird der Benutzername des zweiten Eintrags der Benutzer-Liste ausgegeben durch den Befehl:
> administration.users.user[2].username
=Name
Auch hier wird mit der Tabulator-Taste die Befehlszeile vervollständigt. Wenn mehr als ein Eintrag vorhanden ist, werden dabei auch die vorhandenen Einträge angezeigt. Der Eintrag last bezieht sich immer auf den letzten Eintrag der Liste.

Ausgabe der Listengröße

Mit dem Parameter size wird die Anzahl der Listeneinträge ausgegeben. Beispiel für die Anzahl der Benutzer:
> administration.users.user.size
3

Hinzufügen eines Listeneintrags

Mit dem Parameter add wird einer Liste ein Eintrag am Ende hinzugefügt. Beispiel für das Hinzufügen eines weiteren Benutzers:
> administration.users.user.add
Beispiel für das Hinzufügen von sieben weiteren Benutzern:
> administration.users.user.add=7

Löschen eines Listeneintrags

Mit dem Parameter delete=[x] wird der Eintrag mit der Nummer [x] in der Liste gelöscht. Mit delete=all werden alle Einträge in der Liste gelöscht. Beispiel für das Löschen des Eintrags Nr. 3 in der Liste der Benutzer:
> administration.users.user.delete=3

Verschieben eines Listeneintrags nach oben

Mit dem Parameter sort_up=[x] wird der Eintrag mit der Nummer [x] in der Liste um eine Position nach oben (auf die Position [x-1]) geschoben. Beispiel für das Verschieben des Eintrags Nr. 3 in der Liste der Benutzer nach oben:
> administration.users.user.sort_up=3

Verschieben eines Listeneintrags nach unten

Mit dem Parameter sort_down=[x] wird der Eintrag mit der Nummer [x] in der Liste um eine Position nach unten (auf die Position [x+1]) geschoben. Beispiel für das Verschieben des Eintrags Nr. 3 in der Liste der Benutzer nach unten:
> administration.users.user.sort_down=3

Kopieren eines Listeneintrags

Mit dem Parameter copy=[x] wird der Eintrag mit der Nummer [x] in der Liste kopiert. Dabei wird ein identischer Listeneintrag ans Ende der Liste angehängt. Verfügt der kopierte Listeneintrag über Unterelemente, werden auch diese mitkopiert. Wenn beispielsweise ein Modbus-Gerät kopiert wird, werden nicht nur dessen Kommunikationseinstellungen mit kopiert, sondern auch sämtliche Datenpunkte. Beispiel für das Kopieren des Eintrags Nr. 3 in der Liste der Benutzer:
> administration.users.user.copy=3

Listen innerhalb von Listen

Manche Funktionen der Applikation erfordern Listen innerhalb von Listen. Die Bearbeitung erfolgt analog zu den übergeordneten Listen auf der entsprechenden untergeordneten Sektionsebene. Beispiel für die Abfrage des Typs des Datenpunkts 2 von Modbus-Gerät 1:
> datapoints.modbus.device[1].datapoint[2].datapoint_type
coil

Multiline-Werte

Es besteht auch die Möglichkeit, mehrzeilige Werte innerhalb der CLI einzugeben. Dies ist beispielsweise erforderlich, um Zertifikate, Schlüssel oder Texte für E-Mails und SMS hochzuladen. Diese Werte müssen dann mit -----BEGIN[ID]----- beginnen und mit -----END[ID]----- enden. [ID] kann beliebig gewählt werden, muss aber für BEGIN und END gleich sein. Beispiel für den Text der SMS-Meldung 1:
> messages.sms.sms[1].text
-----BEGIN text-----Message 1 Text-----END text-----

Anzeigen von Aktuellen Werten

Die im Menü Status auf der Seite Aktuelle Werte angezeigten Werte der angelegten Datenpunkte können auch über die CLI ausgelesen werden (einzeln oder alle). Beispiel für die Anzeige der aktuellen Werte aller Datenpunkte:
> status.values.value
input1=0
mdbDp1=1

Anzeigen von Log-Dateien

Bei der Anzeige der Log-Dateien werden die anzuzeigenden Logs durch Kommata getrennt als Indices der Endlosliste view übergeben. Werden keine Log-Dateien angegeben, werden alle Log-Dateien ausgegeben. Es werden jeweils die letzten 10 Zeilen der ausgewählten Log-Dateien ausgegeben. Beispiel:
> status.log.view[httpd,timerd]
2017-05-10 13:18:09 [httpd] User 'insys' (group readwrite) logged in successfully
2017-05-10 13:18:01 [timerd] Added time timer timer1 ()
2017-05-10 13:18:01 [timerd] M3 config read
2017-05-10 13:18:01 [httpd] Webserver started on port 80
2017-05-10 13:18:01 [httpd] M3 config read

Filtern der Log-Datei-Ausgabe

Zur Filterung der ausgegebenen Log-Dateien steht das Programm grep zur Verfügung. Die in grep verfügbaren Parameter werden durch den Parameter -h angezeigt. Sie können auch kombiniert werden.
Beispiel für das Anzeigen aller neuen Log-Meldungen sobald sie auftreten (der Modus kann mit Esc wieder verlassen werden):
> status.log.view[]=grep -f
Beispiel für das Anzeigen aller neuen Anmeldungen am Web-Interface:
> status.log.view[httpd]=grep -f -e logged -e Authentication

Debugging

Manuelles Auslösen einer Aktion

Das manuelle Auslösen einer Aktion dient zum Testen ihrer Wirkung ohne erst abwarten zu müssen, bis das konfigurierte Ereignis eintritt. Je nach Aktion müssen zuerst gewisse Parameter gesetzt werden, mit denen dann die Aktion ausgeführt wird. Beispiel für das Starten von Timer 1:
> help.debug.timer.timer=timer1
> help.debug.timer.change=start
> help.debug.timer.submit
Mit dem ersten Parameter wird der entsprechende Timer ausgewählt. Mit dem zweiten Parameter wird die auszuführende Aktion festgelegt. Mit dem dritten Parameter wird die entsprechende Aktion für den gewählten Timer ausgelöst.

Analyse der Netzwerkverbindungen

Die zum Debugging verfügbaren Befehle werden dem Parameter tool als Wert übergeben. Dafür stehen die fünf Programme ping, ping6, traceroute, traceroute6 und nslookup zur Verfügung. Dahinter wiederum werden die eigenen Parameter des Debugging-Werkzeugs übergeben. Die Syntax des Debugging-Werkzeugs wird durch den Parameter -h angezeigt. Die Ergebnisse werden sofort angezeigt. Die Ausführung der Befehle kann mit Esc oder Strg + C sofort abgebrochen werden. Beispiel für das Versenden von 3 Pings hintereinander an die Adresse 192.168.1.111:
> help.debug.tool=ping -c3 192.168.1.111
> PING 192.168.1.111 (192.168.1.111): 56 data bytes
64 bytes from 192.168.1.111: seq=0 ttl=64 time=2.369 ms
64 bytes from 192.168.1.111: seq=1 ttl=64 time=1.373 ms
64 bytes from 192.168.1.111: seq=2 ttl=64 time=1.370 ms

Abkürzungen

Zur Reduzierung des Eingabeaufwands stehen zusätzlich zur Autovervollständigung Abkürzungen für eine (teilweise) Wiederholung des letzten Befehls zur Verfügung. Mit dem : (Doppelpunkt) werden alle Sektionen des letzten Befehls bis zum letzten Punkt ersetzt. Mit dem . (Punkt) wird je eine Sektion des letzten Befehls an der Stelle des Punkts ersetzt. Beispiele:
> datapoints.modbus.device[1].datapoint[2].datapoint_type
=coil
> :datapoint_type
=coil
> ....datapoint_type
=coil
> ...datapoint[2].datapoint_type
=coil

Lua-Modus

Zum Ausführen von Lua-Skripten in der Applikation können diese in ASCII-Konfigurationsdateien oder im CLI übergeben werden. Neben dem üblichen Funktionsumfang (siehe Lua 5.3 Reference Manual) stehen im Lua-Modus weitere Befehle zur Verfügung.
Um die Funktion der Applikation durch Lua-Befehle nicht versehentlich zu beeinträchtigen, sind folgende Befehle nicht verfügbar: dofile, loadfile, os.execute, os.getenv, os.remove, os.rename, os.setlocale, os.tmpname
Darüber hinaus sind folgende Bibliotheken nicht enthalten: io, coroutine, debug, package

Der Lua-Modus wird mit -----LUA----- betreten und verlassen. Der Lua-Modus ermöglicht die Ausführung komplexer Lua-Skripte.

Die Lua-Funktion "require" ermöglicht es, innerhalb eines Lua-Skripts weitere in Konfigurationsdateien enthaltene Lua-Skripte zu laden und auszuführen.

Mit dem Befehl cli werden innerhalb von Lua Befehle an das CLI übergeben. Beispielsweise aktiviert folgender Befehl den Telnet-Zugriff auf die Kommandozueile:
> cli("administration.cli.telnet_active=1")
Die Ausgabe eines Parameters ist zum Beispiel mit folgendem Befehl möglich:
> print(cli("administration.cli.telnet_active"))
1
Mehrzeilige Werte wie Zertifikate oder Meldungstexte müssen in einem CLI-Aufruf übergeben werden. Entweder wird ein mehrzeiliger Text in [[ und ]] gefasst oder Zeilenumbrüche werden durch das Steuerzeichen \n ersetzt. Beispiel:
> cli("events.messages.message[1].text=-----BEGIN TEXT-----Hello, \nThis email was sent from my Smart Device-----END TEXT-----")
> cli([[events.messages.message[1].text=-----BEGIN TEXT-----
Hello,
This email was sent from my Smart Device
-----END TEXT-----]])

Mit dem Befehl ip_in_net kann abgefragt werden, ob sich eine bestimmte IP-Adresse in einem Netzwerk befindet. Beispielsweise kann man mit folgendem Befehl prüfen, ob sich die IP-Adresse 192.168.1.13 im Netzwerk 192.168.1.0 befindet (die Angabe des Netzwerks kann im CIDR-Format oder mit Netzmaske erfolgen):
> print(ip_in_net("192.168.1.13","192.168.1.0/24"))
true
oder alternativ mit Netzmaske:
> print(ip_in_net("192.168.1.13","192.168.1.0","255.255.255.0"))
true

Mit dem Befehl cidr_to_netmask erfolgt die Umrechnung einer CIDR-Notation in eine Netzmaske. Beispiel:
> print(cidr_to_netmask("24"))
255.255.255.0

Mit dem Befehl netmask_to_cidr erfolgt die Umrechnung einer Netzmaske in CIDR-Notation. Beispiel:
> print(netmask_to_cidr("255.255.255.0"))
24

Mit dem Befehl sleep lässt sich die Ausführung des Lua-Skripts um die im Argument angegebene Anzahl von Sekunden anhalten. Beispielsweise kann man mit folgendem Befehl die Ausführung um 0,7 Sekunden verzögern:
> sleep(0.7)

Beenden der CLI-Sitzung

Die CLI-Sitzung wird beendet durch die Eingabe von exit gefolgt von der Eingabe-Taste.

Zurück zur Übersicht