 |
Online Help icom Data Suite |
Command Line Interface (CLI)
The application provides a command line interface (CLI) for a configuration from the local network or remote via Telnet or SSH.
One parameter after the other will be entered line by line via the CLI and stored in the opened profile. The modifications to the profile will not yet be effective in the running profile with this. The profile must still be activated, i.e. become the running profile, that the modifications to the configuration become effective.
Activating the CLI
Before an access to the application via Telnet or SSH is possible, this must be configured accordingly in the Administration menu on the CLI page. For this, access via Telnet or SSH must be activated and, if the firewall in the router is active, an appropriate exceptional rule must be present and active.
Syntax
The syntax of a parameter is composed of the sections and the parameter, each separated by a full stop.
The sections correspond to the menu structure in the web interface.
The parameter Activate command line via SSH in the Administration menu on the CLI page has the following syntax for example:
> administration.cli.ssh_active
The two sections in front of the parameter correspond to the menu and the page in the web interface here.
The symbol > shown here is the command prompt and not part of the command.
The available sections and parameters depend on the version of the application. These can easily be shown using auto-complete via tabulator key. Pressing the tabulator key shows all available sections of the first level (corresponds to the menus in the web interface). Entering the first letter(s) of a section fallowed by the tabulator key completes the section and pressing the tabulator key again shows all available sections of the next level (corresponds to the pages of this menu in the web interface). Pressing the tabulator key again shows possible further sections or available parameters. In case of lists, the opening square bracket ([) will be output automatically. If this is replaced by a full stop, another click on the tabulator key will output the available list functions.
See also this example for the proceeding to determine the command syntax
Lines starting with a hashtag#will be ignored and can be used as a comment.
Activating a profile
If a profile has been modified using the CLI as described in the following, the modifications will become only effective, if the profile is activated, i.e. made the running profile.
Example for activating the opened profile:
> administration.profiles.activate
>
Example for activating the profile "Profile_2":
> administration.profiles.activate=Profile_2
>
Reading out parameter values
The current value of a parameter is displayed by entering the parameter followed by the enter key. If only the section is entered, all subjacent parameters will be displayed. Example:
> administration.cli.ssh_active
1
> administration.time
administration.time.timezone=Regensburg
Setting parameter values
A new value is assigned to a parameter by entering the parameter followed by an equals sign and the new value. Example:
> administration.cli.telnet_active=1
>
Editing lists
Besides fix parameters, the application has also endless lists like those for the users. The individual entries of a list are enumerated in sequence and can be addressed using this position number. The user name of the second entry of the user list for example is displayed using the command:
> administration.users.user[2].username
=Name
The tabulator key can also be used here to complete the command line. If more than one entry exists, the present entries will also be displayed. The entry last always refers to the last entry of the list.
Displaying a list size
The parameter size displays the number of list entries. Example for the number of users:
> administration.users.user.size
3
Adding a list entry
The parameter add adds an entry to the end of a list. Example for adding another user:
> administration.users.user.add
Example for adding seven further users:
> administration.users.user.add=7
Deleting a list entry
The parameter delete=[x]deletes entry number [x] in the list. The parameter delete=all deletes all existing entries in the list. Example for deleting entry no 3 in the user list:
> administration.users.user.delete=3
Moving a list entry upwards
The parameter sort_up=[x]moves entry number [x] by one position upwards in the list (to position [x-1]). Example for moving entry no 3 upwards in the user list:
> administration.users.user.sort_up=3
Moving a list entry downwards
The parameter sort_down=[x] moves entry number [x] by one position downwards in the list (to position [x+1]). Example for moving entry no 3 downwards in the user list:
> administration.users.user.sort_down=3
Copying a list entry
The parameter copy=[x] copies entry number [x] in the list. An identical list entry will be appended to the end of the list. If the copied list entry has sub-elements, these will also be copied. If a Modbus device is being copied for example, not only its communication settings will be copied, but also all data points. Example for copying entry no 3 in the user list:
> administration.users.user.copy=3
Lists within lists
Some application functions require lists within lists. Editing is along the lines of the higher-level lists on the respective sub-section level. Example for querying the type of data point 2 of Modbus device 1:
> datapoints.modbus.device[1].datapoint[2].datapoint_type
coil
Multi-line values
It is also possible to enter multi-line values within the CLI. This is required to upload certificates, keys, or e-mail and SMS texts for example. These values must then start with -----BEGIN[ID]----- and end with -----END[ID]-----. [ID] can be selected as desired, but must be the same for BEGIN and END. Example for the text of SMS message 1:
> messages.sms.sms[1].text
-----BEGIN text-----Message 1 Text-----END text-----
Displaying current values
The values displayed in the Status menu on the Current values page of the existing data points can also be read out via CLI (individually or all). Example for displaying the current values of all data points:
> status.values.value
input1=0
mdbDp1=1
Displaying the log files
When displaying the log files, the logs to be displayed will be entered in the endless list view separated by commas as indices. If no log files are specified, all log files will be output. The last 10 lines of each selected log file will be output. Example:
> 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
Filtering the log file output
The program grep is available for filtering the log file output. The parameters available in grep are displayed with the parameter -h. They can also be combined.
Example for showing all new log messages as soon as they occur (the mode can be exited again with Esc):
> status.log.view[]=grep -f
Example for showing all new logins at the web interface:
> status.log.view[httpd]=grep -f -e logged -e Authentication
Debugging
Manual triggering of an action
Manual triggering of an action serves for testing its effect without having to wait until the configured event occurs. Depending on the action, certain parameters must be set before that are used to execute the action then. Example for starting timer 1:
> help.debug.timer.timer=timer1
> help.debug.timer.change=start
> help.debug.timer.submit
The first parameter selects the respective timer. The second parameter specifies the action to be executed. The third parameter triggers the respective action for the selected timer.
Analysis of the network connections
The debugging commands are handed over with the parameter tool as value. The five programs ping, ping6, traceroute, traceroute6 and nslookup are available for this. The own parameters of the debugging tool will be handed over again behind this. The syntax of the debugging tool will be displayed with the parameter -h. The results are displayed immediately. The execution of the commands can be aborted immediately with Esc or Ctrl + C. Example for sending 3 subsequent pings to the address 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
Abbreviations
Abbreviations for a (partial) repetition of the last command are available in addition to auto-complete to facilitate the command entry. The:(colon) replaces all sections of the last command until the last full stop. Each . (full stop) replaces one section of the last command at the position of the full stop. Examples:
> datapoints.modbus.device[1].datapoint[2].datapoint_type
=coil
> :datapoint_type
=coil
> ....datapoint_type
=coil
> ...datapoint[2].datapoint_type
=coil
Lua mode
For executing Lua scripts in the application, these can be transmitted in ASCII configuration files or in the CLI. The Lua mode provides further commands besides the usual functional scope (see Lua 5.3 Reference Manual).
To prevent an accidental disturbance of the application function, the following commands are not accidentally: dofile, loadfile, os.execute, os.getenv, os.remove, os.rename, os.setlocale, os.tmpname
Moreover, the following libraries are not contained: io, coroutine, debug, package
The Lua mode will be entered and exited with -----LUA-----. The Lua mode allows to execute complex Lua scripts.
The Lua function "require" allows to load and execute further Lua scripts contained in configuration files within a Lua script.
The command cli transfers commands to the CLI within Lua. The following command activates Telnet access to the command line for example:
> cli("administration.cli.telnet_active=1")
A parameter output is possible using the following command:
> print(cli("administration.cli.telnet_active"))
1
Multi-line values like certificates or message texts must be handed over in one CLI call. Multiline text will either be encapsulated in [[ and ]] or a newline character will be replaced by the control character \n. Example:
> 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-----]])
The command ip_in_net can be used to query, whether a certain IP address is in a network. The following command for example can be used to check, whether the IP address 192.168.1.13 is in the network 192.168.1.0 (the network can be specified in CIDR format or with netmask):
> print(ip_in_net("192.168.1.13","192.168.1.0/24"))
true
or alternatively with netmask:
> print(ip_in_net("192.168.1.13","192.168.1.0","255.255.255.0"))
true
The command cidr_to_netmask can be used to convert a CIDR notation into a netmask Example:
> print(cidr_to_netmask("24"))
255.255.255.0
The command netmask_to_cidr can be used to convert a netmask into CIDR notation Example:
> print(netmask_to_cidr("255.255.255.0"))
24
The command sleep can be used to pause the execution of a Lua script by the number of seconds specified in the argument. The following command for example can delay the execution by 0.7 seconds:
> sleep(0.7)
Closing the CLI session
The CLI session will be closed by entering exit followed by the enter key.