icom OS Routers - Command Line Interface (CLI)
  • 04 Oct 2024
  • PDF

icom OS Routers - Command Line Interface (CLI)

  • PDF

Article summary

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 enabled.

  1. Open the user interface of the router: https://insys.icom

  2. Click in the Administration → Config access menu in the Command line section on (Edit) and check Activate Telnet or Activate SSH and configure the port accordingly.

  3. Click on SUBMIT.

Please note!

If the firewall is active, an appropriate exceptional rule must be present and active. A suitable firewall rule is prepared in the Network → IP filter menu in the IP filter section with the description Local access to command line via SSH. This must be set to active.

Authentication

The authentication will be made using a combination of user name and password that is managed in the Administration → User menu in the Users section.

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 classic 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 classic 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 classic 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. 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 user 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 Guides for the router contain some practical examples for working with Lua.

Closing the CLI session

The CLI session will be closed by entering exit followed by Enter.


Was this article helpful?