CLI command reference.
To get a full XML listing of the commands available in a running NSO instance, use the ncs option --cli-c-dump <file>. The generated file is only intended for documentation purposes and cannot be used as input to the ncsc compiler. The command show parser dump can be used to get a command listing.
Get started with the NSO CLI.
The NSO CLI (command line interface) provides a unified CLI towards the complete network. The NSO CLI is a northbound interface to the NSO representation of the network devices and network services. Do not confuse this with a cut-through CLI that reaches the devices directly. Although the network might be a mix of vendors and device interfaces with different CLI flavors, NSO provides one northbound CLI.
Starting the CLI:
Note the use of the -u parameter which tells NSO which user to authenticate towards NSO. It is a common mistake to forget this. This user must be configured in NSO AAA (Authentication, Authorization, and Accounting).
Like many CLI's there is an operational mode and a configuration mode. Show commands display different data in those modes. A show in configuration mode displays network configuration data from the NSO configuration database, the CDB. Show in operational mode shows live values from the devices and any operational data stored in the CDB. The CLI starts in operational mode. Note that different prompts are used for the modes (these can be changed in ncs.conf configuration file).
NSO organizes all managed devices as a list of devices. The path to a specific device is devices device DEVICE-NAME. The CLI sequence below does the following:
Show operational data for all devices: fetches operational data from the network devices like interface statistics, and also operational data that is maintained by NSO like alarm counters.
Move to configuration mode. Show configuration data for all devices: In this example, this is done before the configuration from the real devices has been loaded in the network to NSO. At this point, only the NSO-configured data like IP Address, port, etc. are shown.
Show device operational data and configuration data:
It can be annoying to move between modes to display configuration data and operational data. The CLI has ways around this.
Show config data in operational mode and vice versa:
Look at the device configuration above, no configuration relates to the actual configuration on the devices. To boot-strap NSO and discover the device configuration, it is possible to perform an action to synchronize NSO from the devices, devices sync-from. This reads the configuration over available device interfaces and populates the NSO data store with the corresponding configuration. The device-specific configuration is populated below the device's entry in the configuration tree and can be listed specifically.
Perform the action to synchronize from devices:
Display the device configuration after the synchronization:
NSO provides a network CLI in two different styles (selectable by the user): J-style and C-style. The CLI is automatically rendered using the data models described by the YANG files. There are three distinctly different types of YANG files, the built-in NSO models describing the device manager and the service manager, models imported from the managed devices, and finally service models. Regardless of model type, the NSO CLI seamlessly handles all models as a whole.
This creates an auto-generated CLI, without any extra effort, except the design of our YANG files. The auto-generated CLI supports the following features:
Unified CLI across the complete network, devices, and network services.
Command line history and command line editor.
Tab completion for the content of the configuration database.
Monitoring and inspecting log files.
Inspecting the system configuration and system state.
Copying and comparing different configurations, for example, between two interfaces or two devices.
Configuring common settings across a range of devices.
The CLI contains commands for manipulating the network configuration.
An alias provides a shortcut for a complex command.
Alias expansion is performed when a command line is entered. Aliases are part of the configuration and are manipulated accordingly. This is done by manipulating the nodes in the alias configuration tree.
Actions in the YANG files are mapped into actual commands. In J-style CLI actions are mapped to the request commands.
Even though the auto-generated CLI is fully functional it can be customized and extended in numerous ways:
Built-in commands can be moved, hidden, deleted, reordered, and extended.
Confirmation prompts can be added to built-in commands.
New commands can be implemented using the Java API, ordinary executables, and shell scripts.
New commands can be mounted freely in the existing command hierarchy.
The built-in tab completion mechanism can be overridden using user-defined callbacks.
New command hierarchies can be created.
A command timeout can be added, both a global timeout for all commands and command-specific timeouts.
Actions and parts of the configuration tree can be hidden and can later be made visible when the user enters a password.
How to customize and extend the auto-generated CLI is described in Plug-and-play Scripting.
The CLI is entirely data model-driven. The YANG model(s) defines a hierarchy of configuration elements. The CLI follows this tree. The NSO CLI provides various commands for configuring and monitoring software, hardware, and network connectivity of managed devices.
The CLI supports two modes:
Operational mode: For monitoring the state of the NSO node.
Configure mode: For changing the state of the network.
The prompt indicates which mode the CLI is in. When moving from operational mode to configure mode using the configure command, the prompt is changed from host# to host(config)#. The prompts can be configured using the c-prompt1 and c-prompt2 settings in the ncs.conf file.
For example:
The operational mode is the initial mode after successful login to the CLI. It is primarily used for viewing the system status, controlling the CLI environment, monitoring and troubleshooting network connectivity, and initiating the configure mode.
A list of base commands available in the operational mode is listed below in the Operational Mode Commands section. Additional commands are rendered from the loaded YANG files.
The configure mode can be initiated by entering the configure command in operational mode. All changes to the network configuration are done to a copy of the active configuration. These changes do not take effect until a successful commit or commit confirm command is entered.
A list of base commands available in configure mode is listed below in the Configure Mode Commands section. Additional commands are rendered from the loaded YANG files.
When using the config mode to enter/set passwords, you may face issues if you are using special characters in your password (e.g., !, "", \, etc.). Some characters are automatically escaped by the CLI, while others require manual escaping. Therefore, the recommendation is to always enclose your password in double quotes " " and avoid using quotes " and backslash \ characters in your password. If you prefer including quotes and backslash in your password, remember to manually escape them, as shown in the example below:
The CLI is started using the ncs_cli program. It can be used as a login program (replacing the shell for a user), started manually once the user has logged in, or used in scripts for performing CLI operations.
In some NSO installations, ordinary users would have the ncs_cli program as a login shell, and the root user would have to log in and then start the CLI using ncs_cli, whereas in others, the ncs_cli can be invoked freely as a normal shell command.
The ncs_cli program supports a range of options, primarily intended for debugging and development purposes (see description below).
The ncs_cli program can also be used for batch processing of CLI commands, either by storing the commands in a file and running ncs_cli on the file, or by having the following line at the top of the file (with the location of the program modified appropriately):
When the CLI is run non-interactively it will terminate at the first error and will only show the output of the commands executed. It will not output the prompt or echo the commands. This is the same behavior as for shell scripts.
To run a script non-interactively, such as a script or through a pipe, and still produce prompts and echo commands, use the --interactive option.
For clispec(5) and confd_lib_maapi(3) refer to Manual Pages.
The CLI comes in two flavors: C-Style (Cisco XR style) and the J-style. It is possible to choose one specifically or switch between them.
Starting the CLI (C-style, Cisco XR style):
Starting the CLI (J-style):
It is possible to interactively switch between these styles while inside the CLI using the builtin switch command:
C-style is mainly used throughout the documentation for examples etc., except when otherwise stated.
If the number of ongoing sessions has reached the configured system limit, no more CLI sessions will be allowed until one of the existing sessions has been terminated.
This makes it impossible to get into the system — a situation that may not be acceptable. The CLI therefore has a mechanism for handling this problem. When the CLI detects that the session limit has been reached, it will check if the new user has the privileges to execute the logout command. If the user does, it will display a list of the current user sessions in NSO and ask the user if one of the sessions should be terminated to make room for the new session.
Once NSO is synchronized with the devices' configuration, done by using the devices sync-from command, it is possible to modify the devices. The CLI is used to modify the NSO representation of the device configuration and then committed as a transaction to the network.
As an example, to change the speed setting on the interface GigabitEthernet0/1 across several devices:
Note the availability of commit flags.
Any failure on any device will make the whole transaction fail. It is also possible to perform a manual rollback, a rollback is the undoing of a commit.
This is operational data and the CLI is in configuration mode so the way of showing operational data in config mode is used.
The command show configuration rollback changes can be used to view rollback changes in more detail. It will show what will be done when the rollback file is loaded, similar to loading the rollback and using show configuration:
The command show configuration commit changes can be used to see which changes were done in a given commit, i.e. the roll-forward commands performed in that commit:
The command rollback-files apply-rollback-file can be used to perform the rollback:
And now the commit the rollback:
When the command rollback-files apply-rollback-file fixed-number 10019 is run the changes recorded in rollback 10019-N (where N is the highest, thus the most recent rollback number) will all be undone. In other words, the configuration will be rolled back to the state it was in before the commit associated with rollback 10019 was performed.
It is also possible to undo individual changes by running the command rollback-files apply-rollback-file selective. E.g. to undo the changes recorded in rollback 10019, but not the changes in 10020-N run the command rollback-files apply-rollback-file selective fixed-number 10019.
This operation may fail if the commits following rollback 10019 depend on the changes made in rollback 10019.
It is possible to process the output from a command using an output redirect. This is done using the | character (a pipe character):
The precise list of pipe commands depends on the command executed. Some pipe commands, like select and de-select, are only available for the show command, whereas others are universally available.
Note that the tab pipe target is used to enforce table output which is only suitable for the list element. Naturally, the table format is not suitable for displaying arbitrary data output since it needs to map the data to columns and rows.
For example, the following are clearly not suitable because the data has a nested structure. It could take an incredibly long time to display it if you use the tab pipe target on a huge amount of data which is not a list element.
This redirect target counts the number of lines in the output. For example:
The include targets is used to only include lines matching a regular expression:
In the example above only lines containing aaa are shown. Similarly lines not containing a regular expression can be included. This is done using the exclude target:
It is possible to display the context for a match using the pipe command include -c. Matching lines will be prefixed by <line no>: and context lines with <line no>-. For example:
It is possible to display the context for a match using the pipe command context-match:
It is possible to display the output starting at the first match of a regular expression. This is done using the begin pipe command:
The output can also be saved to a file using the save or append redirect target:
Or to save the configuration, except all passwords:
The regular expressions are a subset of the regular expressions found in egrep and in the AWK programming language. Some common operators are:
For example, to only display uid and gid do the following:
There are several options for displaying the configuration and stats data in NSO. The most basic command consists of displaying a leaf or a subtree of the configuration by giving the path to the element.
To display the configuration of a device do:
This can also be done for a group of devices by substituting the instance name (ce0 in this case) with Regular Expressions.
To display the config of all devices:
It is possible to limit the output even further. View only the HTTP settings on each device:
There is an alternative syntax for this using the select pipe command:
The select pipe command can be used multiple times for adding additional content:
There is also a de-select pipe command that can be used to instruct the CLI to not display certain parts of the config. The above printout could also be achieved by first selecting the ip container, and then de-selecting the source-route leaf:
A use-case for the de-select pipe command is to de-select the config container to only display the device settings without actually displaying their config:
The above statements also work for the save command. To save the devices managed by NSO, but not the contents of their config container:
It is possible to use the select command to select which list instances to display. To display all devices that have the interface GigabitEthernet 0/0/0/4:
This means to display all device instances that have the interface GigabitEthernet 0/0/0/4. Only the subtree defined by the select path will be displayed. It is also possible to display the entire content of the config container for each instance by using an additional select statement:
The match-all pipe command is used for telling the CLI to only display instances that match all select commands. The default behavior is match-any which means to display instances that match any of the given select commands.
The display command is used to format configuration and statistics data. There are several output formats available, and some of these are unique to specific modes, such as configuration or operational mode. The output formats json, keypath, xml, and xpath are available in most modes and CLI styles (J, I, and C). The output formats netconf and maagic are only available if devtools has been set to true in the CLI session settings.
For instance, assuming we have a data model featuring a set of hosts, each containing a set of servers, we can display the configuration data as JSON. This is depicted in the example below.
Still working with the same data model as used in the example above, we might want to see the current configuration in keypath format.
The following example shows how to do that and shows the resulting output:
To modify a range of instances, at the same time, use range expressions or display a specific range of instances.
Basic range expressions are written with a combination of x..y (meaning from x to y), x,y (meaning x and y) and * (meaning any value), example:
It is possible to use range expressions for all key elements of integer type, both for setting values, executing actions, and displaying status and config.
Range expressions are also supported for key elements of non-integer types as long as they are restricted to the pattern [a-zA-Z-]*[0-9]+/[0-9]+/[0-9]+/.../[0-9]+ and the annotation tailf:cli-allow-range is used on the key leaf. This is the case for the device list.
The following can be done in the CLI to display a subset of the devices (ce0, ce1, ce3):
If the devices have names with slashes, for example, Firewall/1/1, Firewall/1/2, Firewall/1/3, Firewall/2/1, Firewall/2/2, and Firewall/2/3, expressions like this are possible:
In configure mode, it is possible to edit a range of instances in one command:
Or, like this:
Command history is maintained separately for each mode. When entering configure mode from operational for the first time, an empty history is used. It is not possible to access the command history from operational mode when in configure mode and vice versa. When exiting back into operational mode access to the command history from the preceding operational mode session will be used. Likewise, the old command history from the old configure mode session will be used when re-entering configure mode.
The default keystrokes for editing the command line and moving around the command history are as follows.
Move the cursor back by one character: Ctrl-b or Left Arrow.
Move the cursor back by 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 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 the most recently deleted text at the cursor: Ctrl-y.
Scroll backward through the command history: Ctrl-p or Up Arrow.
Scroll forward through the command history: Ctrl-n or Down Arrow.
Search the command history in reverse order: Ctrl-r.
Show a list of previous commands: run the show cli history command.
Capitalize the word at the cursor, i.e. make the first character uppercase and the rest of the word lowercase: Esc-c.
Change the word at the cursor to lowercase: Esc-l.
Change the word at the cursor to uppercase: Esc-u.
Abort a command/Clear line: Ctrl-c.
Quote insert character, i.e. do not treat the next keystroke as an edit command: Ctrl-v/ESC-q.
Redraw the screen: Ctrl-l.
Transpose characters: Ctrl-t.
Enter multi-line mode. Enables entering multi-line values when prompted for a value in the CLI: ESC-m.
Exit configuration mode: Ctrl-z.
It is not necessary to type the full command or option name for the CLI to recognize it. To display possible completions, type the partial command followed immediately by <tab> or <space>.
If the partially typed command uniquely identifies a command, the full command name will appear. Otherwise, a list of possible completions is displayed.
Long lines can be broken into multiple lines using the backslash (\) character at the end of the line. This is primarily useful inside scripts.
Completion is disabled inside quotes. To type an argument containing spaces either quote them with a \ (e.g. file show foo\ bar) or with a " (e.g. file show "foo bar"). Space completion is disabled when entering a filename.
Command completion also applies to filenames and directories:
All characters following a !, up to the next new line, are ignored. This makes it possible to have comments in a file containing CLI commands, and still be able to paste the file into the command-line interface. For example:
To enter the comment character as an argument, it has to be prefixed with a backslash (\) or used inside quotes (").
The /* ... */ comment style is also supported.
When using large configurations it may make sense to be able to associate comments (annotations) and tags with the different parts. Then filter the configuration with respect to the annotations or tags. For example, tagging parts of the configuration that relate to a certain department or customer.
NSO has support for both tags and annotations. There is a specific set of commands available in the CLI for annotating and tagging parts of the configuration. There is also a set of pipe commands for controlling whether the tags and annotations should be displayed and for filtering depending on annotation and tag content.
The commands are:
annotate <statement> <text>
tag add <statement> <tag>
tag clear <statement> <tag>
tag del <statement> <tag>
Example:
To view the placement of tags and annotations in the configuration it is recommended to use the pipe command display curly-braces. The annotations and tags will be displayed as comments where the tags are prefixed by Tags:. For example:
It is possible to hide the tags and annotations when viewing the configuration or to explicitly include them in the listing. This is done using the display annotations/tags and hide annotations/tags pipe commands. To hide all attributes (annotations, tags, and FASTMAP attributes) use the hide attributes pipe command.
Annotations and tags are part of the configuration. When adding, removing, or modifying an annotation or a tag, the configuration needs to be committed similar to any other change to the configuration.
Messages appear when entering and exiting configure mode, when committing a configuration, and when typing a command or value that is not valid:
When committing a configuration, the CLI first validates the configuration, and if there is a problem it will indicate what the problem is.
If a missing identifier or a value is out of range a message will indicate where the errors are:
ncs.conf SettingsParts of the CLI behavior can be controlled from the ncs.conf file. See the ncs.conf(5) in Manual Pages manual page for a comprehensive description of all the options.
There are a number of session variables in the CLI. They are only used during the session and are not persistent. Their values are inspected using show cli in operational mode, and set using set in operational mode. Their initial values are in order derived from the content of the ncs.conf file, and the global defaults as configured at /aaa:session and user-specific settings configured at /aaa:user{<user>}/setting.
The different values control different parts of the CLI behavior:
New commands can be added by placing a script in the scripts/command directory. See Plug-and-play Scripting.
The default behavior is to enforce Unix-style access restrictions. That is, the user's uid, gid, and gids are used to control what the user has read and write access to.
However, it is also possible to jail a CLI user to their home directory (or the directory where ncs_cli is started). This is controlled using the ncs.conf parameter restricted-file-access. If this is set to true, then the user only has access to the home directory.
Help and information texts are specified in several places. In the Yang files, the tailf:info element is used to specify a descriptive text that is shown when the user enters ? in the CLI. The first sentence of the info text is used when showing one-line descriptions in the CLI.
NCS understands multiple quoting schemes on input and de-quotes a value when parsing the command. Still, it uses what it considers a canonical quoting scheme when printing out this value, e.g., when pushing a configuration change to the device. However, different devices may have different quoting schemes, possibly not compatible with the NCS canonical quoting scheme. For example, the following value cannot be printed out by NCS as two backslashes \\ match \ in the quoting scheme used by NCS when encoding values.
General rules for NCS to represent backslash are as follows, and so on. It can only get an odd number of backslashes output from NCS.
\ and \\ are represented as \.
\\\ and \\\\ are represented as \\\.
\\\\\ and \\\\\\ are represented as \\\\\.
A backslash \ is represented as a backslash \ when it is followed by a character that does not need to be escaped but is represented as double backslashes \\ if the next character could be escaped. With remote passwords, if you are using special characters, be sure to follow recommended guidelines, see Configure Mode for more information.
To let NCS pass through a quoted string verbatim, one can do as stated below:
Enable the NCS configuration parameter escapeBackslash in the ncs.conf file. This is a global setting on NCS which affects all the NEDs.
Alternatively, a certain NED may be updated on request to be able to transform the value printed by NCS to what the device expects if one only wants to affect a certain device instead of all the connected ones.
If there are numeric triplets following a backslash \, NCS will treat them as octal numbers and convert them to one character based on ASCII code. For example:
\123 is converted to S.
\067 is converted to 7.
| Command | Description |
|---|---|
| Operator | Description |
|---|---|
-h, --help
Display help text.
-H, --host HostName
Gives the name of the current host. The ncs_cli program will use the value of the system call gethostbyname() by default. The hostname is used in the CLI prompt.
-A, --address Address
CLI address to connect to. The default is 127.0.0.1. This can be controlled by either this flag or the UNIX environment variable NCS_IPC_ADDR. The -A flag takes precedence.
-P, --port PortNumber
CLI port to connect to. The default is the NSO IPC port, which is 4569 This can be controlled by either this flag, or the UNIX environment variable NCS_IPC_PORT. The -P flag takes precedence.
-c, --cwd Directory
The current working directory (CWD) for the user once in the CLI. All file references from the CLI will be relative to the CWD. By default, the value will be the actual CWD where ncs_cli is invoked.
-p, --proto ssh | tcp | console
The protocol the user is using to connect. This value is used in the audit logs. Defaults to ssh if SSH_CONNECTION environment variable is set; console otherwise.
-i, --ip IpAddress | IpAddress/Port
The IP (or IP address and port) which NSO reports that the user is connecting from. This value is used in the audit logs. Defaults to the information in the SSH_CONNECTION environment variable if set, 127.0.0.1 otherwise.
-v, --verbose
Produce additional output about the execution of the command, in particular during the initial handshake phase.
-n, --interactive
Force the CLI to echo prompts and commands. Useful when ncs_cli auto-detects it is not running in a terminal, e.g. when executing as a script, reading input from a file, or through a pipe.
-N, --noninteractive
Force the CLI to only show the output of the commands executed. Do not output the prompt or echo the commands, much like a shell does for a shell script.
-s, --stop-on-error
Force the CLI to terminate at the first error and use a non-zero exit code.
-E, --escape-char C
A special character that forcefully terminates the CLI when repeated three times in a row. Defaults to control underscore (Ctrl-_).
-J, -C
This flag sets the mode of the CLI. -J is Juniper style CLI, -C is Cisco XR style CLI.
-u, --user User
The username of the connecting user. Used for access control and group assignment in NSO (if the group mapping is kept in NSO). The default is to use the login name of the user.
-g, --groups GroupList
A comma-separated list of groups the connecting user is a member of. Used for access control by the AAA system in NSO to authorize data and command access. Defaults to the UNIX groups that the user belongs to, i.e. the same as the groups shell command returns.
-U, --uid Uid
The numeric user ID the user shall have. Used for executing OS commands on behalf of the user, when checking file access permissions, and when creating files. Defaults to the effective user ID (euid) in use for running the command. Note that NSO needs to run as root for this to work properly.
-G, --gid Gid
The numeric group ID of the user shall have. Used for executing OS commands on behalf of the user, when checking file access permissions, and when creating files. Defaults to the effective group ID (egid) in use for running the command. Note that NSO needs to run as root for this to work properly.
-D, --gids GidList
A comma-separated list of supplementary numeric group IDs the user shall have. Used for executing OS commands on behalf of the user and when checking file access permissions. Defaults to the supplementary UNIX group IDs in use for running the command. Note that NSO needs to run as root for this to work properly.
-a, --noaaa
Completely disables all AAA checks for this CLI. This can be used as a disaster recovery mechanism if the AAA rules in NSO have somehow become corrupted.
-O, --opaque Opaque
Pass an opaque string to NSO. The string is not interpreted by NSO, only made available to application code. See built-in variables in clispec(5) and maapi_get_user_session_opaque() in confd_lib_maapi(3). The string can be given either via this flag or via the UNIX environment variable NCS_CLI_OPAQUE. The -O flag takes precedence.
.
Matches any character.
^
Matches the beginning of a string.
$
Matches 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+
Matches one or more rs.
r*
Matches zero or more rs.
r?
Matches zero or one rs.
(r)
Grouping. It matches r.