Commands

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.

Operational Mode Commands

Invoke an Action

Builtin Commands

Configure Mode Commands

Configure a Value

Builtin Commands

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:

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:

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

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

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.

How to customize and extend the auto-generated CLI is described in .

CLI Modes

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:

Starting the CLI

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.

Command Line Options

CLI Styles

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.

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.

Starting the CLI in an Overloaded System

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.

Modifying the Configuration

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.

Command Output Processing

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.

Count the Number of Lines in the Output

This redirect target counts the number of lines in the output. For example:

Search for a String in the Output

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:

Saving the Output to a File

The output can also be saved to a file using the save or append redirect target:

Or to save the configuration, except all passwords:

Regular Expressions

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:

Displaying the Configuration

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 .

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:

Range Expressions

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

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.

Command Line Editing

The default keystrokes for editing the command line and moving around the command history are as follows.

Moving the Cursor

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

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.

Insert Recently Deleted Text

• Insert the most recently deleted text at the cursor: Ctrl-y.

Display Previous Command Lines

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

Capitalization

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

Special

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

CLI Completion

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:

Comments, Annotations, and Tags

All characters following a ! up to the next newline 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>

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.

CLI Messages

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 Settings

Parts of the CLI behavior can be controlled from the ncs.conf file. See the in Manual Pages manual page for a comprehensive description of all the options.

CLI Environment

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:

Customizing the CLI

Adding New Commands

New commands can be added by placing a script in the scripts/command directory. See .

File Access

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 Texts

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.

Quoting and Escaping Scheme

Canonical Quoting Scheme

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

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 for more information.

Escape Backslash Handling

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.

Octal Numbers Handling

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.