The CLI on the Cisco vEdge devices is one of the ways you can configure and monitor these devices. The CLI provides various
commands for configuring and monitoring the software, hardware, and network connectivity of the vSmart controllers and the
vEdge routers. The CLI provides the following features:
-
Displaying help about CLI commands
-
Completing partial commands
-
Editing the command line with keyboard sequences
-
Configuring CLI session settings
-
Filtering command output
-
Adding comments to device configurations
-
Activating and deactivating parts of a configuration
-
Displaying CLI messages
The Cisco SD-WAN CLI design is based on the YANG data modeling language, defined in RFC 6020.
CLI Modes
The CLI has two modes:
-
Operational mode, for monitoring the state of the Cisco vEdge device. When you log in to the CLI, you are in operational mode.
In this mode, you view device status, monitor and troubleshoot the device and network connectivity, enter into configuration
mode, and control the CLI session parameters.
-
Configuration mode, for changing the operational parameters of the Cisco vEdge device. You enter configuration mode by issuing
the configure command in operational mode. This mode has a number of submodes for manipulating different parts of the configuration.
For example, the mode interface-eth1 allows you to configure parameters for Ethernet interface 1. All changes to the device's
configuration are done to a copy of the active configuration, called a candidate configuration. Configuration changes take
effect only when you enter a commit or commit confirmed command and that command is successful.
Start the CLI
Before you begin, make sure the vSmart controller and the vEdge router hardware is set up and the Cisco SD-WAN software is
installed. You must have a direct console connection to the device or network using SSH. If your device is not set up, follow
the installation instructions provided to you with the vSmart controller or the vEdge router before proceeding.
The login prompt for a Cisco vEdge device shows the software version and then prompts for a username and password.
When you log into a vSmart controller or a vEdge router, you are prompted to enter your user name and password. Once you enter
your password, you are automatically placed at the CLI prompt.
For security reasons, each time you log out of the device, the CLI session ends and you are required to log in again to access
the CLI.
CLI Prompts
The prompt indicates the mode the CLI is in:
-
host-name#: The host name followed by a hash mark indicates that the CLI is in operational mode. An operational mode prompt is similar
to vsmart#.
-
host-name(config)#: When the CLI is in configuration mode, the string config is added to the prompt. For example, a configuration mode
prompt is similar to vsmart(config)#. If you are configuring a lower hierarchy in the commands, the prompt also indicates
that level. For example, if you are configuring Ethernet interface 1 for a VPN, in the hierarchy vpn > interface, the configuration
mode prompt is vsmart(config-interface-eth1)#. The CLI prompt shows only the parent hierarchy, not the full path to the command,
so that the CLI prompt never gets too long.
To change the operational mode prompt, use the prompt1 operational command:
vsmart# prompt1 eve@vsmart#
eve@vsmart#
To change the configuration mode prompt, use the prompt2 operational command:
vsmart# prompt2 eve@vsmart(config)#
eve@vsmart(config)#
Configure CLI Session Settings
The following are the default CLI session settings for a Linux terminal:
vsmart# show cli
autowizard false
complete-on-space false
history 100
idle-timeout 1800
ignore-leading-space true
output-file terminal
paginate true
prompt1 \h\M#
prompt2 \h(\m)#
screen-length 30
screen-width 80
service prompt config true
show-defaults false
terminal xterm-256color
timestamp disable
To change the session values, use the command names listed in the output above. For more information on the commands, see
Operational Commands .
Command Hierarchies
CLI commands are organized in a hierarchy that groups commands that perform related or similar functions. For example, in
operational mode, commands that display information about OMP are collected under the show omp command hierarchy. In configuration mode, commands that configure OMP properties are collected under the omp command hierarchy.
Display Help about CLI Commands
To list the available CLI commands, along with a short description of the command, type a ? (question mark).
If you type ? at the prompt, the CLI displays a list of available commands. In operational mode, you see:
vsmart# ?
Possible completions:
autowizard Automatically query for mandatory elements
clear Clear parameter
clock System clock
commit Confirm a pending commit
complete-on-space Enable/disable completion on space
config Manipulate software configuration information
debug Debugging commands
exit Exit the management session
file Perform file operations
help Provide help information
history Configure history size
idle-timeout Configure idle timeout
job Job operations
leaf-prompting Automatically query for leaf values
logout Logout a user
monitor Monitor a file
no Negate a command or set its defaults
nslookup Look up a DNS name
paginate Paginate output from CLI commands
ping Ping a host
poweroff Shut down the system
prompt1 Set operational mode prompt
prompt2 Set configure mode prompt
quit Exit the management session
reboot Reboot the system
request Perform an action
screen-length Configure screen length
screen-width Set CLI screen width
show Show information about the system
tcpdump Perform tcpdump on a network interface
timestamp Enable/disable the display of timestamp
tools Tools commands
traceroute Trace connectivity to a host
vdig Asynchronous FQDN resolution
vping Send L2, L3, L7 probes to remote host
vshell System shell
If you type tools and ? at the prompt, the CLI displays a list of available commands for tools. In operational mode, you see:
vm9# tools ?
Possible completions:
consent-token Access restricted functionality using Consent Token
core-state Show Core state
cpu-util Show CPU Utilization
flood-ping Flood-ping a host
ike-debug IKE debug tools
internal (TESTBED) Internal commands
ip-route Display route table
iperf Network bandwidth measurement tool
netstat Display network status
nping Network packet generation tool
ss Display network statistics
stun-client STUN client protocol tool
support Support commands
vtysh Integrated shell for Quagga routing software suite
Note
|
To access vtysh commands, see Quagga docs on the Quagga Routing website.
|
If you type ? at the prompt after entering configuration mode, you see:
vsmart(config)# ?
Possible completions:
apply-policy Apply network policy
banner Set banners
omp OMP information
policy Configure policy
security Configure security
snmp Configure SNMP
system Configure System
vpn VPN Instance
---
abort Abort configuration session
clear Remove all configuration changes
commit Commit current set of changes
describe Display transparent command information
do Run an operational-mode command
end Terminate configuration session
exit Exit from current mode
help Provide help information
load Load configuration from an ASCII file
no Negate a command or set its defaults
pwd Display current mode path
revert Copy configuration from running
rollback Roll back database to last committed version
save Save configuration to an ASCII file
show Show a parameter
top Exit to top level and optionally run command
validate Validate current configuration
If you type ? after a command name, the CLI shows all possible completions for that command. For example:
vsmart# show interface vpn 0 ?
Possible completions:
eth0 eth1 | <>
If you type help before a command name, it will you give you more information about the command. For example:
vsmart# help show cli
Help for command: show cli
Display cli settings
The show parser dump command also displays information about available commands and their syntax.
Enter User-Defined Strings
For many configuration commands, you define a string that identifies an instance of a configurable object. For example, when
you create user accounts, you configure a user-defined string for the username:
vEdge(config-system)# aaa user eve
In this command, the strings "aaa" and "user" are Cisco SD-WAN software keywords, and the string "eve" is a user-defined string.
User-defined strings can include all uppercase and lowercase letters, all digits, spaces, and all special characters except
for angle brackets (< and >).
To include a space or an exclamation point (!) in a user-defined string, either type a backslash (\) before the space or enclose
the entire string in quotation marks (" "). For example:
vEdge(config)# banner login "Remember to log out when you are done!"
vEdge(config-banner)# show full-configuration
banner
login "Remember to log out when you are done!"
!
vEdge(config-banner)#
vEdge(config-system)# organization-name My\ Company
vEdge(config-system)# show configuration
system
organization-name "My Company"
!
vEdge(config-system)#
Complete Partial Commands and Strings
The CLI provides command completion. It recognizes commands and options based on the first few letters you type so that you
do not always have to remember or type the full command or option name.
To display a list of all possible command or option completions, type the partial command followed immediately by a question
mark. For example:
vsmart@# s?
Possible completions:
screen-length Configure screen length
screen-width Set CLI screen width
show Show information about the system
To complete a command or option that you have partially typed, press the tab key after you have typed a partially completed
command name. If the partially typed letters begin a string that uniquely identifies a command, the complete command name
is displayed. Otherwise, a list of possible completions is displayed.
Command completion also works with other strings, such as filenames, directory names, interface names, and usernames.
To enable command completion when you press the space bar, enable it for the duration of the terminal session:
vEdge# complete-on-space true
When this is enabled, you can press the tab key or the space bar to complete a partially typed command name or variable string.
Command completion is disabled within quoted strings. So if an argument contains spaces and you quote them with a backslash
(for example, prefix-list my\ list) or with quotation marks (for example, prefix-list "my list"), you cannot use command completion. Space completion does not work with filenames.
Edit the Command Line with Keyboard Sequences
You can use keyboard sequences in the CLI to move around and edit text on the command line itself. You can also use keyboard
sequences to scroll through a list of recently executed commands. The following table lists some of the CLI keyboard sequences.
Table 1.
Category
|
Action
|
Keyboard Sequence
|
Move the cursor
|
Move the cursor back one character.
|
Ctrl-B or Left Arrow
|
|
Move the cursor back one word.
|
Esc-B or Alt-B
|
|
Move the cursor forward one character.
|
Ctrl-F or Right Arrow
|
|
Move the cursor forward one word.
|
Esc-F or Alt-F
|
|
Move the cursor to the beginning of the command line.
|
Ctrl-A or Home
|
|
Move the cursor to the end of the command line.
|
Ctrl-E or End
|
Delete characters
|
Delete the character before the cursor.
|
Ctrl-H, Delete, or Backspace
|
|
Delete the character following the cursor.
|
Ctrl-D
|
|
Delete all characters from the cursor to the end of the line.
|
Ctrl-K
|
|
Delete the whole line.
|
Ctrl-U or Ctrl-X
|
|
Delete the word before the cursor.
|
Ctrl-W, Esc-Backspace, or Alt-Backspace
|
|
Delete the word after the cursor.
|
Esc-D or Alt-D
|
Insert recently deleted text
|
Insert the most recently deleted text at the cursor.
|
Ctrl-Y
|
Display previous command lines
|
Scroll backward through the list of recently executed commands.
|
Ctrl-P or Up Arrow
|
|
Scroll forward through the list of recently executed commands.
|
Ctrl-N or Down Arrow
|
|
Search the command history in reverse order.
|
Ctrl-R
|
|
Show list.
|
|
Capitalization
|
Capitalize the word at the cursor; that is, make the first character uppercase and the rest of the word lowercase.
|
Esc-C
|
|
Change the word at the cursor to all lowercase.
|
Esc-l
|
Special cases
|
Cancel a command; that is, clear a line.
|
Ctrl-C
|
|
Quote insert character; that is, do not treat the next keystroke as an edit command.
|
Ctrl-V/Esc-Q
|
|
Redraw the screen.
|
Ctrl-l
|
|
Transpose characters.
|
Ctrl-T
|
|
Enter multiline values when prompted for a value in the CLI (not available when editing a CLI command).
|
Esc-M
|
|
Exit configuration mode.
|
Ctrl-Z
|
Filter Command Output
You can filter the output from a command by adding the pipe (|) symbol at the end of the command, followed by one of the filtering
commands listed in the following table. You can chain together a series of filters on a single command line.
Table 2.
Filter
|
Description
|
append filename
|
Append output text to a file.
|
begin regular-expression
|
Begin with the line that matches a regular expression.
|
best-effort
|
Display data even if the data provider is unavailable, or continue loading from a file even if failures are occurring.
|
count
|
Count the number of lines in the output.
|
csv
|
Display the outfield fields in a comma-separated format.
|
display
|
Display the output as XML.
|
exclude regular-expression
|
Exclude lines that match a regular expression.
|
include regular-expression
|
Include lines that match a regular expression.
|
linnum
|
Enumerate lines in the output.
|
match-all
|
All selected filters must match.
|
match-any
|
At least one selected filter must match.
|
more
|
Paginate the output.
|
nomore
|
Suppress pagination of the output.
|
notab
|
Display each output field on a separate line instead of in a table.
|
repeat seconds
|
Execute the command repeatedly, every specified number of seconds.
|
save filename
|
Save the output to a file.
|
select
|
For tabular output, select the columns to display.
|
tab
|
Enforce the table output of fields.
|
until regular-expression
|
End the display with the line that matches a regular expression.
|
Use Regular Expressions
The regular expressions available for use in filtering commands are a subset of those used in the UNIX egrep command and in the AWK programming language. The following table lists some common operators.
Table 3.
Operator
|
Action
|
.
|
Match any character.
|
^
|
Match the beginning of a string.
|
$
|
Match the end of a string.
|
[abc...]
|
Character class, which matches any of the characters abc... Character ranges are specified by a pair of characters separated
by a -.
|
[^abc...]
|
Negated character class, which matches any character except abc.
|
r1 | r2
|
Alternation. It matches either r1 or r2.
|
r1r2
|
Concatenation. It matches r1 and then r2.
|
r+
|
Match one or more rs.
|
r*
|
Match zero or more rs.
|
r?
|
Match zero or one rs.
|
(r)
|
Grouping. It matches r.
|
Understand CLI Messages
The CLI displays messages at various times, such as when you enter and exit configuration mode, commit a configuration, and
type a command or value that is not valid.
When you type an invalid command or value, a CLI message indicates the nature of the error:
vsmart# show c
Possible completions:
certificate Display installed certificate properties
cli Display cli settings
clock System clock
configuration Display configuration history
control Display Control Information
When you commit a configuration, the CLI first validates the configuration. If there is a problem, the CLI indicates the nature
of the problem:
Entering configuration mode terminal
vsmart(config)# no vpn 0
vsmart(config)# commit
Aborted: 'vpn' : Cannot delete vpn 0
vsmart(config>)#
Count the Number of Lines in Command Output
To count the number of lines in the output from a command, use the count filtering command. For example:
vsmart# show interface | count
Count: 17 lines
Display Line Numbers in Command Output
To display line numbers in the output, use the linnum command filter. For example:
vsmart# show interface | linnum
1: interface vpn 0 interface eth0
2: ip-address 10.0.1.12/24
3: if-admin-status Up
4: if-oper-status Up
5: encap-type null
6: mtu 1500
7: hwaddr 00:50:56:00:01:02
8: speed-mbps 1000
9: duplex full
10: rx-packets 3035
11: tx-packets 1949
12: interface vpn 0 interface eth1
13: if-admin-status Down
14: if-oper-status Down
15: hwaddr 00:0c:29:81:00:17
16: rx-packets 0
17: tx-packets 0
Search for a String in Command Output
To have the command output include only lines matching a regular expression, use the include command filter. For example:
vsmart# show cli | include screen
screen-length 30
screen-width 80
To have the command output include only the lines not containing a regular expression, use the exclude filtering command. For example:
vsmart# show cli | exclude e
history 100
prompt1 \h\M#
prompt2 \h\(m)#
To display the output starting at the first match of a regular expression, use the begin command filter. For example:
vsmart# show cli | begin show
show-defaults false
terminal linux
timestamp disable
To end the command output when a line matches a regular expression, use the until command filter. For example:
vsmart# show cli | until history
autowizard false
complete-on-space true
history 100
Save Command Output to a File
To save command output to a file, use the save
filename or append
filename command filter. For example:
vsmart# show running-config omp | save filename
To save the configuration except for any passwords, add the exclude password command filter:
vsmart# show running-config system | exclude password | save filename
Configure a Device from the CLI
To configure a vSmart controller or vEdge router directly from the device, enter configuration mode:
vsmart# config
Then type either the full configuration command or type one command at a time to move down through the command hierarchy.
Here is an example of typing a full configuration command:
vsmart(config)# vpn 1 interface ge0/1 ip address 1.1.1.1/16
Here is an example of moving down the command hierarchy by typing one command at a time:
vsmart(config)# vpn1
vsmart(config-vpn-1)# interface eth1
vsmart(config-interface-eth1)# ip address 1.1.1.1/16
vsmart(config-interface-eth1)#
To move to another portion of the hierarchy, simply type the name of the top-level command. For example:
vsmart(config-interface-eth1)# policy
vsmart(config-policy)#
To look at the configuration changes:
vsmart(config-policy)# top show configuration
vpn 1
interface eth1
ip address 1.1.1.1/16
shutdown
!
!
To commit the changes:
vsmart(config-policy)# commit
Commit complete.
Add Comments in a Configuration
All characters following an exclamation point (!) character up to the next newline in a configuration are ignored. This allows
you to include comments in a file containing CLI commands and then paste the file into the CLI. To enter the ! character as
an argument or to include it in a password, prefix it with a backslash (\) or place it inside quotation marks (" ").
Delete Commands from a Configuration
Use the no command to delete commands from a configuration. For example:
vsmart(config)# do show running-config
vpn 1
interface eth1
ip address 1.1.1.1/16
auto-negotiation
shudown
no proxy-arp
!
!
vsmart(config)# no vpn 1 interface eth1 ip address
vsmart(config)# commit
commit complete.
vsmart(config)# do show running-config
vpn 1
interface eth1
auto-negotiation
shudown
no proxy-arp
!
!