Category     

NCOS: Command Line Interface (CLI) - Getting Started

« Go Back

Information

 
Content

NCOS: Command Line Interface (CLI) - Getting Started

Products Supported: AER31x0, AER2100, MBR1400, MBR1200B, CBA850, CBA750B, IBR300, IBR6x0, IBR11x0. Click here to identify your router.


 

Quick Links

Summary
Terminology
Configuration
Accessing the CLI
Editing Configurations
Lists and Arrays
Directory Structure
Using the CLI
Commands
Reading and Writing Values
Related Articles

Summary

Cradlepoint's CLI is a captive, text-based interface for configuring, managing, and debugging Cradlepoint routers.

This document contains a brief introduction to the Cradlepoint Command Line Interface (CLI). A powerful feature available in all Series 3 Cradlepoint routers. Keep in mind this topic if far to expansive to cover everything in one document. We encourage you to take advantage of our cli database and Google is a wonderful learning tool. The database has links to other topics, commands and several use-case examples.

Terminology:

  • Prompt (or Command Prompt):  A command line interpreter allowing users to execute commands directly to the machine.
  • Command:  A “command” is a single word instruction for the router to process. Commands are entered in the "command prompt."
  • Argument:  An argument refers to the text that follows the command. Most commands have optional arguments controlling and influencing the way a command will run. Arguments can typically be discovered by running the command followed by the “--help” argument. I.E: “help wan”.
[administrator@AER1600-d59: /]$ help wan         
Show all the attached wan devices and their current state.         
Usage: wan [monitor] [UID] [CONFIG...]         
CONFIG: Can be any number of --key=[value] pairs as defined in the /config/wan/rules2 config section.         
    If the optional [value] argument is ommited then the current value (if any) will be printed.                    
    Get example: wan cp1 --ip_mode --static.ip_address                                                              
    Set example: wan cp1 --ip_mode="static" --static.ip_address="10.0.0.1" --static.netmask="255.0.0.0"             
[administrator@AER1600-d59: /]$
  • SCP:  Secure Copy.  A method for securely transferring files between devices.
  • ConfigStore:  A collection of files accessed through the router's cli.
  • Working Directory:  The directory currently displayed in the terminal.
  • Hierarchical File System:  A method for organizing and displaying directory's with there subsequent folders and files.
  • JSON:  A lightweight data-interchange format that is easy for humans to read and write. (www.json.org)
  • Parent Directory:  Refers to the directory above another directory. Every directory, except the root directory, lies beneath another directory. The higher directory is called the parent directory, and the lower directory is called a subdirectory.

Configuration

Configuration Difficulty: Intermediate

Enabling the SSH Server

NCOS 6.X.X or newer

Note: On your router local SSH access is enabled by default. It is only necessary to configured SSH if previously disabled, or remote access is required.

  • Step 1: Log into the router's NCOS Page. For help with logging in please click here.
  • Step 2: Click on System then Administration from the navigation menu.
  • Step 3: Click on Local Management and verify that Enable SSH Server is checked.
    • The SSH Server Port can be changed away from the default SSH port of 22 to a port of your choosing. This is highly recommended for any situation where Remote SSH will be enabled.
  • Step 5: Click Save.
  • Step 6: Click on Remote Admin from the navigation menu.
  • Step 7: Place a checkmark next to Allow Remote SSH Access.
  • Step 8: Click Save.

Accessing the CLI

CradlePoint Series 3 routers are designed to support standards-based SSH-2 clients. Many modern operating systems (such as GNU/Linux or Apple OSX) include an SSH client that can be run directly from the computer’s terminal. For these platforms simply open the Terminal and run the “ssh” command followed by the username and password for the router. For Microsoft Windows computers, we recommend using the free and well-supported PuTTY, SSH client, available here.

ssh admin@192.168.0.1
    User-added image

PuTTY's web page is a great resource. Their site contains additional documentation that can assist in successfully make an SSH connection for several different operating systems. The only details you should need to provide are the username, password and IP address of the router. The default username is always “admin.".
        User-added image

Conn ecting to Cradlepoint's SSH Server console through the UI
  • Step 1: Log into the router's NCOS Page. For help with logging in please click here.
  • Step 2: Click on System, System Control, and then Device Options.
  • Step 3: Click on the Device Console button. This will open up a new window.
        User-added image
        User-added image
Connecting to Cradlepoint's SSH Server console through NCM

Note: To access the console in NCM your account must have Prime.

  • Step 1: Log into https://www.cradlepointecm.com. For additional information on NCM, please click here.
  • Step 2: Click on the Devices tab, then select the router you would like to console into.
  • Step 3: With the router selected click Remote Connect and then Console, this will open the command prompt window.
    • Note: CLI Session History can be saved by clicking the check-mark in the menu bar of the Console Session.
       User-added image
       
       User-added image

Editing Configurations

Editing your configurations in the default windows text editor, is an exercise in nightmarish futility. We highly recommend using notepad++. Notepad++ is a powerful, free, source code and text editor, that will correctly format your configs and makes editing a joyous pleasure!

Saving the CLI Output to a text File

CLI session history can be saved by selecting the check mark icon.

       User-added image


Lists and Arrays

A directory may contain lists in place of a single directory folder. In the output below, there are 6 folders (0-5.) Using a list number to make configuration changes, may NOT actually modify the folder you intended to. If previous configuration changes were made, the folder number may now relate to a totally separate ConfigStore.

[administrator@AER1600-d59: /]$ ls /config/wan/rules                                                                    
0/ 1/ 2/ 3/ 4/ 5/                                                                                                       
[administrator@AER1600-d59: /]$

It is always recommended to make changes by ID field. Running the a "get" command followed by the folder number and the "/_id_" argument, will return the folders unique ID. Editing with unique ID's and not list numbers, ensures any changes are made to the intended folder.

[administrator@AER1600-d59: /]$ get /config/wan/rules/1/_id_                                                            
"00000001-dea3-3ccd-a78d-e0196084396f"                                                                                  
[administrator@AER1600-d59: /]$

After a field is modified the router will automatically increment the ID field. When more than on person is modifying a config, we recommend changing the first digit if the ID to prevent overlapping changes from occurring.


Directory Structure

Main Directories

Config - Configuration store for all of the routers configuration

Status - Shows the current status of various router features and services.

Control - Initiates changes to the routers features and services.

State - Elements of config/status that are not pushed to NCM.


Using the CLI

When successful the command prompt will begin with this output:

[admin@MBR1400-301: /]$

The first word after [, represents the username you logged in with (admin). Your routers system ID is next after the @ symbol (MBR1400-301), and lastly, the current working directory (/) complete this initial output. When using the CLI your "working directory" is extremely important. Entering a command in the current directory will always dictate the corresponding output to be displayed. Every directory represents a “ConfigStore” and that determines the context for many commands.

Navigating the CLI

An important part of a command line shell, is the notion of a hierarchical file system. The hierarchical file system is backed by a tree structure that contains the directories and files of a systems storage. On Cradlepoint routers, the file system hierarchy is backed by the router's configuration, its status, and the control system or “ConfigStore.”

The ConfigStore can be represented and visualized as a central nervous system. It facilitates interactions to an alive portal containing the routers current state and its configuration. We will expand on this as we move forward, but try to remember that the files and directories are live elements of the router. Any changes to these files or directories will result in immediate application and proliferation through the routers internal subsystems.

Basic navigation commands:

Syntax

[administrator@AER1600-d59: /]$ ls                                                                                      
state/   control/ status/  config/                                                                                      
[administrator@AER1600-d59: /]$ cd /state                                                                               
[administrator@AER1600-d59: /state]$
  • ls - Lists directories and files.

  • cd - Changes the current directory.

  • get - Retrieves values depending on the current directory.

The highest working directory is call the “root” directory (/). All other directory's are linked back to the root.

[admin@MBR1400-301: /]$

The “ls” command lists the directories and files in your current working directory. Running the “ls” command from the “root” directory returns:

[admin@MBR1400-301: /]$ ls 
control/           status/            config/

You can change the working directory using the “cd” command, followed by the desired directory. Running “cd config” changes the current working directory to “config/”. Notice the prompt now displays our current working configuration as, “/config/.”

[admin@MBR1400-301: /]$ cd config
[admin@MBR1400-301: /config]$

If “ls” is ran from the config/ directory, all of the directories and files for “config/" will be presented.

[admin@MBR1400-301: /config]$ ls
ethernet/  wan/       lan/       shell/     qos/       dns/      
firewall/  failover/  alerts/    system/    hotspot/   wwan/     
gre/       routing/   dhcpd/     webfilter/ wlan/      vpn/      
stats/

You can move from any directory to an other without navigating back to the root, “cd” will always allow us to change the current working directory. To change from one subsystem “cd system” changes the current working directory to “config/system/”.

[admin@MBR1400-301: /config]$ cd system

[admin@MBR1400-301: /config/system]$ ls
mac_monitor/          local_domain          timezone             
at_passthrough_proxy/ serial/               upnp/                
ui_activated          snmp/                 first_boot           
dyndns/               system_id             email/               
gps/                  users/                power/               
ntp/                  pci_dss               wipc/                
qxdmproxy/            logging/              admin/               
watchdog/             disable_leds          reboot_schedule/     
dst_enabled

The “get” command by itself may be used to return the values of all files in the current working directory. “get” followed by a filename or directory will return only the values specific to that location. For example, to see whether or not daylight-savings time has been enabled, enter cd /config/system/ and move to that directory.

[administrator@AER1600-d59: /]$ cd /config/system/                                                                      
[administrator@AER1600-d59: /config/system]$

Once /config/system/ is our current directory, enter “get dst _ enabled” and the current status of the respective configuration will be displayed.

[admin@MBR1400-301: /config/system]$ get dst_enabled
true

Jumping to the root directory is a breeze, simply use the "cd" command! Moving up one directory is as equally, stress free, "cd .." will transport you up one directory..

[admin@MBR1400-301: /config/system/logging/]$ cd ..
[admin@MBR1400-301: /config/system/]$ cd cd
[admin@MBR1400-301: /]$

Searching for values in the configstore using only the "cd" and "ls" command can be frustrating and often overly time consuming. Thankfully, we have the "grep" command. The "grep" command is a command line utility that looks for expressions that match your grep parameters.

[admin@DeskRouter: /]$ find / | grep zsis
/status/zsis
/status/zsis/status
/config/webfilter/zsis
/config/webfilter/zsis/dyndns
/config/webfilter/zsis/dyndns/password
/config/webfilter/zsis/dyndns/user_name
/config/webfilter/zsis/dyndns/dnsservers
/config/webfilter/zsis/dyndns/dnsservers/0
/config/webfilter/zsis/dyndns/dnsservers/0/priority
/config/webfilter/zsis/dyndns/dnsservers/0/ip_address

One thing you really should take advantage of is the “tab-completion” feature. Tab completion is fully supported and will drastically reduce the number of key strokes required to enter a command. To use this feature type the first part of a command or path name and then, smash the tab key, tab completion will automatically finish the command! Equally helpful, when the word is not unique in the current directory, hitting the tab key twice will display a list of available commands!

[administrator@AER1600-d59: /]$ help                                                                                  
 state control status config

Commands

To see a complete list of commands type “help”.

[administrator@AER1600-d59: /]$ help                                                                                  

Available Commands:                                                                                         
    SupportQA       adduser         append          arpdump         atterm          banner          bgp           
    cd              clear           clients         cpconnect       date            delete          deluser       
    devices         diff            ecm             edit            exit            factory_reset   find          
    get             grep            help            inspect         ips             lan             log           
    ls              mkdir           nemo            netfilter       netstat         nhrp            ospf          
    passwd          ping            ping6           pwd             qos             reboot          reset         
    resources       rip             ripng           route           rtpolicy        serial          set           
    sleep           sms             ssh             stp             switch          tcpdump         telnet        
    threads         traceroute      uptime          vlan            vpn             vrrp            wan           
    wireless        workqueue       xfrm            zebra                                                         

Available Aliases:                                                                                            
    cat  => get                                                                                                   
    dir  => ls                                                                                                    
    ll   => ls -l 1                                                                                               
    more => get                                                                                                   
    post => append                                                                                                
    put  => set                                                                                                   
    quit => exit                                                                                                  
    rm   => delete     

To get help for a specific command run: "help CMD"

Basic Commands

Words in bold are the actual commands. Always remember these commands are context specific and their output will change depending on the current directory.

  • help - Display available commands or help for a specific command
  • cd - Change directory
  • ls - List settings/keys and directories in current directory
  • get - Display the value of a setting/key
  • set - Set the value of parameter
  • inspect - Show properties of directories and settings/keys, such as type, value, parameters, etc.
  • log - Shows the log - many optional parameters (-f) for filtering
  • SupportQA - Provides debugging data for support cases
  • devices - Displays network devices (interfaces) connected to the router. (-v verbose output)
  • information About interfaces including couters)
  • tcpdump - TCPDump is a powerful tool for monitoring packets that traverse an interface
  • ecm - Displays NCM information, such as state, routerID, NCM data usage, monthly estimate, etc. Also can be used to start/stop/restart client and register/unregister device.
  • route - Displays all the routing tables
  • switch - Displays ethernet switch status, speed/duplex, VIDs
  • wireless - Displays wireless configuration and status - optional parameters for other functions, such as channel - selection, site survey, etc.

Reading and Writing Values

The "get" and "set" commands are used to read or write a desired value to the ConfigStore. All values in the ConfigStore are formatted in JSON (http://json.org). Because the file system is also the ConfigStore, you can run “get” from the root directory, displaying the complete contents of its ConfigStore. The “get”, “set”, “append”, and “delete” commands all take the current working directory into consideration, always know your current directory. Therefore, any argument following a command must be a path inside or in reference to the current directory. Remember, “ls” will display all contents of the current directory.

Here are a few examples that illustrate multiple ways in which you can view the contents of a system.

You can run get or ls from the root directory and specify the directory's absolute path as its argument. An absolute path is any path that begins with the "/" character. "/" indicates the path and any subsequent paths located in the root directory.

[admin@MBR1400-301: /]$ get /config/system/logging/level
"info"

[admin@MBR1400-301: /]$ ls /config/system/logging   
console        level          firewall       enabled       
max_logs       modem_debug    remoteLogging
The same thing can be accomplished by changing the current working directory, then running the command from there.
[admin@MBR1400-301: /]$ cd /config/system/logging/
[admin@MBR1400-301: /config/system/logging]$ ls
console        level          firewall       enabled       
max_logs       modem_debug    remoteLogging/

[admin@MBR1400-301: /config/system/logging]$ get level
"info"

A "." following the path name, refers to its current working directory and can also be used as an argument to the "get" command. Notice the output of"." is very similar to the output of "ls." however, it will be formatted in JSON and includes all contents of its sub-directories.

[admin@MBR1400-301: /config/system/logging]$ get .
{
    "console": false,
    "enabled": true,
    "firewall": false,
    "level": "info",
    "max_logs": 1000,
    "modem_debug": false,
    "remoteLogging": {
        "enabled": false,
        "system_id": false,
        "utf8_bom": true
    }
}

If we change to the parent directory we can run "get" again, providing we point to the relative path of an item we would like to see.

[admin@MBR1400-301: /config/system/logging]$ cd ..
[admin@MBR1400-301: /config/system]$ get logging/level
"info"

You may have noticed the log level is set at "info." Info will only store messages of "informational priority" or higher in the system log. If you want to change the logging level to something different, use the “inspect” command and any available configuration values will be displayed. To change the value use our trusty “set” command and modify the value.

[admin@MBR1400-301: /]$ cd /config/system/logging/    

[admin@MBR1400-301: /config/system/logging]$ inspect level
Path: /config/system/logging/level
Name   Type     Current value   Default Value   Options
----------------------------------------
level  select   info            info            debug, info, warning, error, critical

It never hurts to verify the current value of a configuration prior to modification. Here, we will quickly check that our logging level is indeed "info."

[admin@MBR1400-301: /config/system/logging]$ get level
"info"

To change the logging level, run "set" followed by a chosen value. Remember, the set value MUST be valid JSON. In this example the string value("debug"), will be encapsulated in quotes.

[admin@MBR1400-301: /config/system/logging]$ set level "debug"

Running "get" again verifies the modification was valid and accepted.

[admin@MBR1400-301: /config/system/logging]$ get level
"debug"

When values are invalid or incorrectly formatted, the value is rejected and parsed by the router's internal error handling process. To test that the systems validation procedure is functioning correctly, we can purposely enter an invalid value or argument.

[admin@MBR1400-301: /config/system/logging]$ set level 3.14
Error: invalid value (3.14) at: ['config', 'system', 'logging', 'level']
Reason: invalid option

[admin@MBR1400-301: /config/system/logging]$ set level __not_json__
Invalid value: No JSON object could be decoded

[admin@MBR1400-301: /config/system/logging]$ set level "not_an_option" 
Error: invalid value (not_an_option) at: ['config', 'system', 'logging', 'level']
Reason: invalid option

Related Articles/Links


Published Date: 07/14/2017


 
Knowledge Home | Product