 |
Online help |
Command Line Interface (CLI)
The router 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 router 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 is active, an appropriate exceptional rule must be present and active. A suitable firewall rule is prepared in the Netfilter menu on the IP filter page with the description Local access to command line via SSH and must only be set to active.
Authentication
The authentication will be made using a combination of user name and password that is managed in the Administration menu on the Users page.
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 available sections and parameters depend on the respective device and the installed plug-in cards. 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.
Lines starting with a hashtag # will be ignored and can be used as a comment.
See the Command reference page for this as well.
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 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
administration.time.ntp_peer=ptbtime1.ptb.de
Entering 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
>
Renaming entries
An entry, such as the name of a profile or container, can be renamed by entering the old name and the new name, separated by a blank.
Example for renaming the profile "quick_start_profile" to "new_profile":
> administration.profiles.rename=quick_start_profile new_profile
>
Editing lists
Besides fix parameters, the router 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. From version 2.6, it is possible to specify a number to add multiple list entries with one command. 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. The parameter delete=last deletes the last entry. 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. Example for copying entry no 3 in the user list:
> administration.users.user.copy=3
Lists within lists
Some router 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 connection check interval of the interface on position 2 of the WAN chain on position 1:
> wan.wans.wan_chain[1].interface[2].check_interval
10
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 message 1:
> events.messages.message[1].text
-----BEGIN text-----Message 1 Text-----END text-----
Displaying status information
The information displayed in the Status menu of the web interface can also be read out via the CLI. Status information can also be inserted in messages as current values. Example for the display of the voltage at input 1 of the LTE card in slot 2:
> status.lte2.input_voltage_1
12.25 V
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[deviced,cli]
2016-06-16 11:36:54 [clid] Started
2016-06-16 13:37:06 [deviced] Remove device node /dev/ttyUSB3
2016-06-16 13:37:07 [deviced] Turning on modem in slot 2
2016-06-16 13:37:19 [deviced] USB: detected Gemalto PLS8 application port
2016-06-16 13:37:19 [deviced] Add device node /dev/ttyUSB2
2016-06-16 13:56:34 [clid] Reconfiguring
2016-06-16 13:56:34 [clid] Starting SSH server for CLI
2016-06-16 14:07:10 [deviced] Turning off modem in slot 2
2016-06-16 14:07:10 [deviced] USB: detected Gemalto PLS8 application port
2016-06-16 14:07:10 [deviced] Remove device node /dev/ttyUSB2
2016-06-16 14:07:12 [deviced] Turning on modem in slot 2
2016-06-16 14:07:24 [deviced] USB: detected Gemalto PLS8 application port
2016-06-16 14:07:24 [deviced] Add device node /dev/ttyUSB3
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
Displaying event-dependent information
All available parameters of the event-dependent information can be displayed in an interactive CLI session using auto-complete (using the tabulator key, see syntax above):
> events.info[
event_id
username
successful
remotehost
sender
message
modem
link_name
changed_to
This event-dependent information can only be used by the event that has triggered the message or ASCII configuration. They can be listed there separately or all in the form parameter=value:
> events.info[username]
insys
> events.info
event_id=4
username=insys
remotehost=192.168.1.2:58608
successful=yes
In order to evaluate event-dependent information in an ASCII configuration, this must contain a Lua script.
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 closing output 1 of the card in slot 3:
> help.debug.output.output=3.1
> help.debug.output.change=close
> help.debug.output.submit
The first parameter specifies the output to be set. The second parameter specifies the action to be executed. The third parameter triggers the respective action at the selected output.
Analysis of the network connections
The debugging commands are handed over with the parameter tool as value. The six programs ping, ping6, traceroute, traceroute6, nslookup and tcpdump 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
Executing an AT command
The command for executing AT commands at_command will be forwarded to the parameter tool as value. This is followed by the used modem and the AT command itself. The results are displayed immediately. Example for identifying the modem chipset in slot 2:
> help.debug.tool=at_command lte2 ati
ati
Cinterion
PLS8-E
REVISION 01.090
OK
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:
> wan.wans.wan_chain[1].interface[2].check_interval
=10
> :check_interval
=10
> ....check_interval
=10
> ...interface[2].check_interval
=10
Lua mode
For executing Lua scripts on the router, these can be transmitted in ASCII configuration files or in the CLI.
The Lua mode provides the following commands besides the usual functional scope (see Lua 5.3 Reference Manual): cli, cli_log, lua_log, netmask_to_cidr, cidr_to_netmask, ip_in_net, sleep
To prevent an disturbance of the router 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 libraries within a Lua script. These can be uploaded to the router like a regular ASCII configuration file, but must have the file extension ".lua". Moreover, the Lua mode must be entered with -----LUA----- at the begin of the file. When calling "require", only the file name without the file extension will be handed over.
The command cli transfers commands to the CLI within Lua.
The following command sets the location to "Regensburg” for example:
> cli("administration.hostnames.location=Regensburg")
A parameter output is possible using the following command:
> print(cli("administration.hostnames.location"))
Regensburg
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 cli_log makes an entry into the CLI log.
The following command for example writes the string "abc" to the CLI log:
> cli_log("abc")
The command lua_log makes an entry into the Lua log.
The Lua log will only be created, if entries are made using this command.
The router itself will not write any entries to this log.
The following command for example writes the string "xyz" to the Lua log:
> lua_log("xyz")
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)
The Configuration Guide for the router contain practical examples for working with Lua.
Closing the CLI session
The CLI session will be closed by entering exit followed by the enter key.