Knowledge Base

 
Reset Search
 

 

Article

NCOS: Command Line Interface (CLI) - Getting Started

« Go Back

Information

 
Content

NCOS: Command Line Interface (CLI) - Getting Started

Products Supported: AER1600/1650 Series, AER31x0*, AER2100*, AER2200 Series, COR IBR200, COR IBR600B/C Series, COR IBR900 Series, COR IBR1100 Series, COR IBR1700, MBR1400*, MBR1200B*, ARC CBA850, ARC CBA750B*, IBR300*, IBR6x0*, IBR11x0*. See Identify Cradlepoint Products to identify your device.
*Discontinued model

 


Quick Links

Summary
Terminology
Configuration
Access the CLI
CLI Window Features
Using the CLI
Lists and Arrays
Commands
Reading and Writing Values
Related Articles

Summary

Cradlepoint's Command Line Interface (CLI) is a captive, text-based interface that can be used for managing, troubleshooting, and viewing the operating state of Cradlepoint devices.

This document contains a relatively brief introduction to the Cradlepoint CLI, a powerful feature available in all Series 3 Cradlepoint devices. For more information, see the Knowledgebase article, NCOS: CLI - Article Database. This article contains links to other topics, commands, and several use-case examples. General information on using command line interfaces is also easily found by using web search engines.

Terminology:

  • Argument—an argument refers to the text that follows a command. Most commands have optional arguments to control the way a command runs and the output it provides. If a command accepts arguments, the arguments can be viewed by typing the command "help" followed by the command name (e.g. "help wan") or by typing the command name followed by "--help" (e.g. "wan --help").
    [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@AER3100-fb2: /]$
  • CLI—a command line interface that allows users to issue commands directly to a device.
  • Command—a command is a single word instruction for the device to process. Commands are typed at the "command prompt."
  • Command Prompt—a line of machine-generated text in a CLI that accepts typed commands for execution by pressing the Enter key. See Using the CLI in this article for more information on the command prompt.
  • ConfigStore—a hierarchical collection of directories and files on a Cradlepoint device that contain readable/writable settings that describe the device's state. 
  • Hierarchical file system—a method for organizing and displaying directories, sub-directories, and files.
  • JSON—a lightweight, human-readable, data-interchange format. (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 sub-directory.
  • SCP (Secure Copy)—a method for securely transferring files between devices.
  • Working directory—the directory currently displayed at the command prompt.

Configuration

Configuration Difficulty: Intermediate

Enable the SSH Server

NCOS 6.X.X or newer

Note: Local SSH access is enabled on devices by default. It is only necessary to configure SSH if it has been previously disabled, or if remote access is required.

1. Log into the device's NCOS Page. For help with logging, see NCOS: Accessing the Setup Pages of a Cradlepoint router.

2. Navigate to SYSTEM > Administration > Local Management.

3. Verify that the Enable SSH Server option is checked on the Local Management page.

Figure 1: Enable SSH Server in Local Management
Enable Local Management option in NCOS (System > Administration > Local Management)

4. The SSH Server Port value can be changed from the default SSH port of 22 to a port of your choice. Changing the SSH Server Port value is recommended whenever Remote SSH will be enabled.

5. Click the Save button. 

6. Click on Remote Admin in the navigation menu.

7. Select the option to Allow Remote SSH Access.

Figure 2: Allow Remote SSH Access in Remote Admin
Allow Remote SSH Acess (System > Administration > Remote Admin

8. Click the Save button.

Access the CLI

If your NetCloud Manager (NCM) account has either the Prime or Enterprise tier, the recommended method for opening a CLI is to use the DEVICES > Remote Connect > Console option. Use the following steps to open a CLI to a Cradlepoint device through NCM.

1. Log into NCM using this link: NCM Login Page

2. Click the DEVICES tab, and then select the device to open the console for.

3. Click the Remote Connect menu, and then select the Console option to open the CLI  window.

Figure 3: Open a CLI from the NCM Remote Connect Menu
       User-added image
       
Figure 4: Cradlepoint Device CLI Window
       User-added image
 
Connect to Cradlepoint's SSH Server console through the NCOS UI
An alternate method for opening a command-line interface to a Cradlepoint device (for accounts with a Prime or Enterprise tier) is to use the System > System Control page in NCOS.

1. Log into the device's NCOS Page. For help with logging in, see NCOS: Accessing the Setup Pages of a Cradlepoint router.

2. Click the System tab, click the System Control item, and then select Device Options.

3. Click on the Device Console button. This will open up a CLI window for the device.

Figure 5: NCOS Device Options
        NCOS Device Options, for opening a console from the device UI (System > System Control > Device Options

Figure 6: Device Console
        User-added image


If you do not have access to NCM or to the NCOS GUI, a CLI can be opened to a Cradlepoint device using an SSH client. 

Cradlepoint Series 3 devices support standards-based SSH-2 clients. Most modern operating systems (such as GNU/Linux or Apple OS X) include an SSH client that can be run directly from the computer’s terminal. For these platforms, open the terminal, type the “ssh” command followed by the username and password for the device, and then press the Enter key. An example of an ssh command is shown below: 

ssh admin@192.168.0.1 [password]

For Microsoft Windows operating systems, we recommend using the free and well-supported PuTTY SSH client, available from the PuTTY Download page.

Figure 7: PuTTY SSH Client-Configuration Example

   User-added image

The PuTTY web site is a great resource for finding additional documentation that can help in making SSH connections for several different operating systems. The only details you typically need to provide are the username, password, and IP address of the device. The default username  for Cradlepoint devices is always “admin."

Figure 8: CLI via PuTTY
        User-added image


 

CLI Window Features

The CLI window title bar contains the following buttons, from left to right: 

  • Help User-added image icon—opens a help panel with information on using the CLI.
  • Save User-added image icon—saves the output displayed in the CLI window to a text file.
  • Resize User-added image icon—resizes the CLI window to full-screen or to the default size.
  • Close User-added image icon—closes the CLI window and terminates the remote connection to the device.

Figure 9: CLI (Console) Window Features
User-added image


Using the CLI

When you have opened a CLI, the command prompt begins with output in the following form:

[admin@AER3100-fb2: /]$

admin—username of the logged-in user
@AER3100-fb2—the system ID of the device
/ (root)—the current working directory
$—represents where commands and arguments can be typed

Navigating the CLI

The CLI provides access to the readable/writable directories and files on Cradlepoint devices. The following top-level directories are accessible from the CLI:

  • config—configuration settings for various device features and services
  • control—initiates changes to a device's features and services.
  • status—shows the current status of various device features and services.
  • state—elements of config/status that are not pushed to NCM.

Each of these directories contain files and other directories that comprise the device ConfigStore. The ConfigStore, taken as a whole, represents the current state of a device. Any changes to these files or directories are applied immediately and change the state of the device.

When using the CLI, note that commands execute relative to the current working directory or specified path.

Basic navigation commands:

Syntax

[administrator@AER3100-fb2: /]$ ls                                                                                      
state/   control/ status/  config/                                                                                      
[administrator@AER3100-fb2: /]$ cd /state                                                                               
[administrator@AER3100-fb2: /state]$
  • ls—lists directories and files in the current working directory or path
  • cd—changes the current working directory

The highest working directory is referred to as the “root” directory (/). 

[admin@AER3100-fb2: /]$

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

[admin@AER3100-fb2: /]$ ls 
status/     control/     config/     state/

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

[admin@AER3100-fb2: /]$ cd config
[admin@AER3100-fb2: /config]$

If “ls” is ran from the config/ directory, all of the directories and files in the “config/" directory are displayed.

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

To move to the root directory, use the "cd" command.

[admin@AER3100-fb2: /config/system/]$ cd
[admin@AER3100-fb2: /]$

To move up one directory, use "cd .."

[admin@AER3100-fb2: /config/system/logging/]$ cd .. 
[admin@AER3100-fb2: /config/system/]$

Searching for files and directories in the ConfigStore using only the "cd" and "ls" commands can be inefficient. Use the "grep" command to search the ConfigStore using a regular expression.

[admin@AER3100-fb2: /]$ 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


Cradlepoint's CLI supports the “tab-completion” feature. Use this feature to have the CLI finish your partially-typed commands, file names, and paths. To use the feature, type the first few characters of the item's name, then press the Tab key once. Press the tab key twice after typing a command to display a list of available commands.

[administrator@AER3100-fb2: /]$ help                                                                                  
 state control status config

Reading and Writing Values

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

The following examples illustrate several ways you can view the contents of a file or directory.

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@AER3100-fb2: /]$ get /config/system/logging/level
"info"

[admin@AER3100-fb2: /]$ 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@AER3100-fb2: /]$ cd /config/system/logging/
[admin@AER3100-fb2: /config/system/logging]$ ls
console        level          firewall       enabled       
max_logs       modem_debug    remoteLogging/

[admin@AER3100-fb2: /config/system/logging]$ get level
"info"

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

[admin@AER3100-fb2: /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@AER3100-fb2: /config/system/logging]$ cd ..
[admin@AER3100-fb2: /config/system]$ get logging/level
"info"

In the example above the log level is set to "info." The "info" log level only stores messages in the system log that are of "informational priority" or higher. To view the logging level, use the “inspectcommand to display any available configuration settings. To change the value, use the "set" command.

[admin@AER3100-fb2: /]$ cd /config/system/logging/    

[admin@AER3100-fb2: /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

Verify the current value of a configuration setting before changing the setting. The following example verifies the logging level is set to "info."

[admin@AER3100-fb2: /config/system/logging]$ get level
"info"

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

[admin@AER3100-fb2: /config/system/logging]$ set level "debug"

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

[admin@AER3100-fb2: /config/system/logging]$ get level
"debug"

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

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

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

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


Lists and Arrays

A directory may contain lists in place of a single directory folder. In the example output below there are six, zero-indexed (0-5) folders. Using a list number to make configuration changes, may NOT actually modify the folder you intend. If previous configuration changes were made, the folder number may now represent a different ConfigStore.

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

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

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

After a field is modified the device automatically increments the ID field. When more than one person is modifying a configuration, we recommend changing the first digit if the ID to prevent overlapping changes from occurring.

Commands

To see a complete list of commands type “help” at the command prompt in the CLI.

[administrator@AER3100-fb2: /]$ 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 device. (-v verbose output)
  • information—info about interfaces (including devices)
  • tcpdump—TCPDump is a powerful tool for monitoring packets that traverse an interface
  • 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

Related Articles/Links


Published Date: 07/14/2017

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255