Classic CLI overview

In this chapter, ‟CLI” refers to the classic CLI unless otherwise specified.

CLI structure

The SR OS CLI is a command-driven interface accessible through the console, Telnet, or secure shell (SSH). The CLI can be used for the configuration and management of routers.

The SR OS CLI command tree is a hierarchical inverted tree. The operational root level is the highest level of this tree. When the user enters a CLI session, the user is in the operational root context. Below this level are other tree levels for the major command groups; for example, configure commands and show commands are levels below the operational root level.

The CLI is organized so that related commands with the same scope are at the same level or in the same context. Sublevels or subcontexts have related commands with a more refined scope.

Note: The CLI engine used to execute scripts is the primary CLI engine configured with config>system>management-interface>cli>cli-engine {[classic-cli] [md-cli]}.

Navigating in the CLI

The following table describes command syntax symbols used in this guide.

Table 1. Command syntax symbols
Symbol Description

|

A vertical line indicates that only one of the parameters within the brackets or braces can be selected.

[ ]

Brackets indicate optional parameters.

{ }

Braces indicate that one of the parameters must be selected.

[{ }]

Braces within square brackets indicate that the parameters are optional, but if one is selected, the information within the braces is required.

Bold

Bold indicates commands and keywords.

Italic

Italics indicates that you must enter text for the parameter.

CLI contexts

Use the CLI to access, configure, and manage Nokia routers. CLI commands are entered at the command line prompt. Access to specific CLI commands is controlled by the permissions set by your system administrator. Entering a CLI command makes navigation possible from one command context (or level) to another.

When the user enters a CLI session, the user is in the operational root context. Navigate to another level by entering the name of successively lower contexts. For example, at the command prompt (#), enter configure or config. See Command completion for alternative syntax for the same command. The active context displays in the command prompt.

A:cses-E11# config
A:cses-E11>config#

In a CLI context, enter commands at that context level by entering the text. Press <Enter> to move to a lower context. The user can also include commands from lower context at one context level as long as the command and parameter syntax is correct.

The following example shows two methods to navigate to a service SDP ingress level.

Method 1:

A:cses-E11# configure service epipe 6 spoke-sdp 2:6 ingress 
*A:cses-E11>config>service>epipe>spoke-sdp>ingress#

Method 2:

A:cses-E11>config# service
A:cses-E11>config>service# epipe 6
*A:cses-E11>config>service>epipe# spoke-sdp 2:6
*A:cses-E11>config>service>epipe>spoke-sdp# ingress
*A:cses-E11>config>service>epipe>spoke-sdp>ingress#

The CLI returns an error message if the syntax is incorrect. For example, if the user enters rooter for the root command, it would result in an error.

*A:cses-E11>config# rooter
Error: Bad command.

The command parameter is the means by which a value is passed to the command processing program. The user must enter the value according to the syntax rules and, where applicable, the defined range. In the previous example, ‟6” and ‟2:6” are the parameter values that the user must enter to execute the command. The value ‟6” is the value for the Epipe service identifier parameter. For the value ‟2:6”, ‟2” is the value for the SDP identifier parameter and ‟6” is the value for the virtual circuit identifier.

Operational root and global commands

The commands in the following table are available at the operational root level of the CLI hierarchy. For the command descriptions, see the respective command sections in this guide. For descriptions of the clear, monitor, show, and tools commands, see the 7450 ESS, 7750 SR, 7950 XRS, and VSR Clear, Monitor, Show, and Tools Command Reference Guide.

Table 2. Operational root commands
Command Description

admin

Enters the administrative context for system operations

bof

Enters the context to configure the boot options file

clear

Clears statistics or resets the operational state

configure

Enters the configuration context

[no] debug

Enters the context to enable or disable debugging and specify debug options

environment

Enters the environment configuration context

file

Enters the context for file system commands

help

Displays help in the CLI

monitor

Enters the context to monitor statistics

password

Enters the context to change the user CLI login password

show

Shows operational information

tools

Enters the tools context for troubleshooting and debugging

Global commands are commands that can be entered at any level in the CLI hierarchy. To display the list of all system global commands, enter help globals in the CLI.

The global commands are listed in the following table. For the command descriptions, see the respective command sections in this guide.

Table 3. Global commands
Command Description

back

Navigates to the parent context

candidate

Enters the context to configure candidate parameters

echo

Echoes the text that is typed in. The primary use is to display messages to the screen within an exec file.

enable-admin

Enables the user to become a system administrator

exec

Executes the contents of a text file as if they were CLI commands entered at the console

exit

Returns to the previous higher context

help

Displays help in the CLI

history

Displays a list of the most recently entered commands

logout

Terminates the CLI session

mrinfo

Requests multicast router information

mstat

Traces a multicast path from a source to a receiver and displays multicast packet rate and loss information (IGMP-based)

mstat2

Traces a multicast path from a source to a receiver and displays multicast packet rate and loss information (UDP-based)

mtrace

Traces a multicast path from a source to a receiver (IGMP-based)

mtrace2

Traces a multicast path from a source to a receiver (UDP-based)

oam

Provides OAM test suite options. See the 7450 ESS, 7750 SR, 7950 XRS, and VSR OAM and Diagnostics Guide.

ping

Verifies the reachability of a remote host

pwc

Displays the present or previous working context of the CLI session

sleep

Causes the console session to pause operation (sleep) for 1 s or for the specified number of seconds. The primary use is to introduce a pause in the execution of an exec file.

ssh

Opens a secure shell connection to a host

telnet

Connects to a host using Telnet

traceroute

Determines the route to a destination address

tree

Displays a list of all commands at the current level and all sublevels

write

Sends a console message to a specific user or to all users with active console sessions

CLI environment commands

The CLI environment commands listed in the following table are found in the environment context of the operational root of the CLI tree. These commands control session preferences for a single CLI session. For more information on the commands, see the respective command sections in this guide.

Table 4. CLI environment commands
Command Description

alias

Enables the substitution of a command line by an alias

create

Enables or disables the use of a create parameter check

kernel

Enables or disables the kernel

more

Enables the CLI output to be displayed one screen at a time, awaiting user input to continue

reduced-prompt

Configures the maximum number of higher-level CLI context nodes to display by name in the CLI prompt for the current CLI session

saved-ind-prompt

Saves the indicator in the prompt

shell

Enables or disables the shell

suggest-internal-objects

Enables the suggestion of internally created objects while auto-completing

terminal

Configures the terminal screen length for the current CLI session

time-display

Specifies whether time should be displayed in local time or UTC

time-stamp

Specifies whether the timestamp should be displayed before the prompt

Getting help in the CLI

The help system commands and the ? key display different types of help in the CLI. The following table lists the help commands.

Table 5. Online help commands
Command Description

help

Describes the help system

help globals

Displays information about global commands

help edit

Displays information about all editing keystrokes

help special-characters

Displays information about all special characters that can be entered at the command prompt

?

Displays context-sensitive help information and displays a full list of options and commands available from the current context

When entered at the root context, displays a full list of top-level contexts and global commands

command ?

command parameter ?

command keyword ?

Displays the available syntax options for the command, lists the associated parameters and keywords, and lists all commands available from the command context

string?

Lists all commands available in the current context that start with string

command string?

command parameter string?

command keyword string?

Lists all commands, parameters, or keywords available in the command context that start with string

stringTab

Completes a partial command name (auto-completion) or lists available commands that match string

The tree and tree detail system commands are useful when searching for a command in a lower-level context.

The following example shows a partial list of the tree and tree detail command outputs on a 7750 SR.

tree and tree detail command outputs

*A:cses-E11>config# tree

+---router
| +---aggregate
| +---allow-icmp-redirect
| +---allow-icmp6-redirect
| +---autonomous-system
| +---bfd
| | +---abort
| | +---begin
| | +---bfd-template
| | | +---echo-receive
| | | +---multiplier
| | | +---receive-interval
| | | +---transmit-interval
| | | +---type
| | +---commit
| +---bgp
| | +---add-paths
| | | +---ipv4
| | | +---ipv6
| | | +---label-ipv4
| | | +---label-ipv6
| | | +---vpn-ipv4
| | | +---vpn-ipv6
| | +---advertise-external
| | +---advertise-inactive
| | +---aggregator-id-zero
| | +---auth-keychain
| | +---authentication-key
| | +---backup-path
| | +---best-path-selection
| | | +---always-compare-med
| | | +---as-path-ignore
| | | +---deterministic-med
| | | +---ignore-nh-metric
| | | +---ignore-router-id
| | +---bfd-enable
| | +---cluster

*A:cses-E11>config# tree detail
...
+---router [<router-name>]
| +---no aggregate <ip-prefix/ip-prefix-length>
| | aggregate <ip-prefix/ip-prefix-length> [summary-only] [as-set]
[aggregator <as-number:ip-address>] [black-hole [generate-icmp]]
[community <comm-id>]
| | aggregate <ip-prefix/ip-prefix-length> [summary-only] [as-set]
[aggregator <as-number:ip-address>] [community <comm-id>] [indirect
<ip-address>]
| +---allow-icmp-redirect
| | no allow-icmp-redirect
| +---allow-icmp6-redirect
| | no allow-icmp6-redirect
| +---autonomous-system <autonomous-system>
| | no autonomous-system
| +---bfd
| | +---abort
| | +---begin
| | +---bfd-template <[32 chars max]>
| | | no bfd-template <[32 chars max]>
| | | +---echo-receive <milli-seconds>
| | | | no echo-receive
| | | +---multiplier <[3..20]>
| | | | no multiplier
| | | +---no receive-interval
| | | | receive-interval <milli-seconds>
| | | +---no transmit-interval
| | | | transmit-interval <milli-seconds>
| | | +---no type
| | | | type {cpm-np}
| | +---commit
| +---bgp
| | no bgp
| | +---add-paths
| | | no add-paths
| | | +---ipv4 send <send-limit>
| | | | ipv4 send <send-limit> receive [none]
| | | | no ipv4
| | | +---no ipv6
| | | | ipv6 send <send-limit>
| | | | ipv6 send <send-limit> receive [none]
| | |   +---label-ipv4 send <send-limit>
| | |   label-ipv4 send <send-limit> receive [none]
| | |   no label-ipv4
| | +---label-ipv6 send <send-limit>
| | |   label-ipv6 send <send-limit> receive [none]
| | |   no label-ipv6
| | | +---no vpn-ipv4
| | | | vpn-ipv4 send <send-limit>
| | | | vpn-ipv4 send <send-limit> receive [none]
| | | +---no vpn-ipv6
| | | | vpn-ipv6 send <send-limit>
| | | | vpn-ipv6 send <send-limit> receive [none]
| | +---advertise-external [ipv4] [ipv6] [label-ipv4] [label-ipv6]
| | | no advertise-external [ipv4] [ipv6] [label-ipv4] [label-ipv6]
| | +---advertise-inactive
| | | no advertise-inactive
| | +---aggregator-id-zero
| | | no aggregator-id-zero
| | +---auth-keychain <name>
| | +---authentication-key <authentication-key|hash-key> [hash|hash2|custom]

The CLI command prompt

By default, the CLI command prompt indicates the device being accessed, the active CPM, and the current CLI context. For example, the prompt: A:cses-E11>config>router>if# indicates that the active CPM is CPM A, the user is on the device with the hostname cses-E11, and the current context config>router>interface. In the prompt, the separator used between contexts is the ‟>” symbol. The active CPM can be A or B on the 7750 SR, and A, B, C, or D on the 7950 XRS.

At the end of the prompt, there is either a pound sign (#) or a dollar sign ($). A ‟#” at the end of the prompt indicates the context is an existing context. A ‟$” at the end of the prompt indicates the context has been newly created. Contexts are newly created for logical entities when the user first navigates into the context.

Because there can be a large number of sublevels in the CLI, the environment command reduced-prompt no of nodes in prompt allows the user to control the number of levels displayed in the prompt.

WARNING:

In CLI command configurations, allowed values in parameter strings are printable, 7-bit ASCII characters. If the string contains special characters, (#, $, space), the entire string must be enclosed within double quotes ("). Double quotes within a string are not supported. Parameter strings input by the user must follow this format. This rule supersedes all related parameter descriptions found in this guide.

When changes are made to the configuration file, a ‟*” appears in the prompt string (*A:cses-E11), indicating that the changes have not been saved. When an admin save command is executed, the ‟*” disappears. This behavior is controlled by the saved-ind-prompt command in the environment context.

Displaying configuration contexts

The info, info detail, and objective commands display the configuration for the current level. The info command shows non-default configurations. The info detail command shows the entire configuration for the current level, including defaults. The info objective command provides an output objective that controls the configuration parameters to be displayed.

info and info detail command outputs

The following example displays the output from the info command and the info detail command.

*A:cses-E11>config>router# interface system
*A:cses-E11>config>router>if# info
----------------------------------------------
            address 10.10.0.1/32
----------------------------------------------
*A:cses-E11>config>router>if# 


*A:cses-E11>config>router>if# info detail
----------------------------------------------
            address 10.10.10.103/32 broadcast host-ones
            no description
            no arp-timeout
            no allow-directed-broadcasts
            tos-marking-state trusted
            no local-proxy-arp
            no proxy-arp
            icmp
                mask-reply
                redirects 100 10
                unreachables 100 10
                ttl-expired 100 10
            exit
            no mac
            no cflowd
            no shutdown
----------------------------------------------
*A:cses-E11>config>router>if#

exec Files

The exec command allows you to execute a text file of CLI commands as if it were typed at a console device.

The exec command and the associated exec files can be used to conveniently execute a number of commands that are always executed together in the same order. For example, an exec command can be used to define a set of commonly used standard command aliases.

The echo command can be used within an exec command file to display messages on screen while the file executes.

Arguments can be specified with the exec command. These arguments are passed in to be used inside the text file that includes the CLI commands. The passing of arguments with the exec command only works in the classic CLI. The passing of arguments with the exec command cannot be used in the MD-CLI.

For example, if the file cf3/Test.txt contains the following set of CLI commands:

echo $(1) 
echo $(2) 
echo $(3) 

then executing the following commands:

# exec cf3:/Test.txt -arguments var1=10 var2=20 var3=30

or

# exec cf3:/Test.txt -arguments 10 20 30

produces the following output:

10
20
30

CLI script control

SR OS provides centralized script management for CLI scripts that are used by CRON and the Event Handling System (EHS). A set of script policies and script objects can be configured to control such things as:

  • where scripts are located (local compact FTP server)

  • where to store the output of the results

  • how long to keep historical script result records

  • how long a script may run

If the scripts are located on local compact flash devices, the user must ensure that the scripts are on the compact flash devices of both CPMs so that operation of EHS continues as expected if a CPM switchover occurs.

Only one script can execute at a time. An SNMP table (smRunTable in the DISMAN-SCRIPT-MIB) is used as both an input queue of scripts waiting to be executed and for storage of records for completed scripts. If the input queue is full, the script request is discarded.

Entering CLI commands

The following sections outline the steps to entering CLI commands.

Command completion

The CLI supports both command abbreviation and command completion. If the keystrokes entered are enough to match a valid command, the CLI displays the remainder of the command syntax when Tab or Spacebar is pressed. When typing a command, Tab or Spacebar invokes auto-completion. If the keystrokes entered are sufficient to identity a specific command, auto-completion completes the command. If the letters are not sufficient to identify a specific command, pressing Tab or Spacebar displays commands matching the letters entered.

System commands are available in all CLI contexts.

Unordered and unnamed parameters

In a command context, the CLI accepts command parameters in any order as long as the command is formatted in the proper command keyword and parameter syntax. Command completion works as long as enough recognizable characters of the command are entered.

The following output shows the command syntax for static-route-entry.

*A:cses-E11>config>router# static-route-entry ?
 - no static-route-entry <ip-prefix/prefix-length> [mcast] 
 - static-route-entry <ip-prefix/prefix-length> [mcast] 

<ip-prefix/prefix-*> : ipv4-prefix    - a.b.c.d (host bits must be 0)
                       ipv4-prefix-le - [0..32]  
                       ipv6-prefix    - x:x:x:x:x:x:x:x   (eight 16-bit pieces)
                                        x:x:x:x:x:x:d.d.d.d 
                                        x - [0..FFFF]H
                                        d - [0..255]D
                       ipv6-prefix-le - [0..128]  
<mcast>              : keyword - Indicates that static-route being configured 
                       is used for mcast table only

 [no] backup-tag      - Create/Configure or Delete/Deconfigure backup tag for
                        static-route-entry
 [no] black-hole      + Create/Configure or Delete/Deconfigure blackhole
                        nexthop for static-route-entry
 [no] community       - Create/Configure or Delete/Deconfigure community for
                        static-route-entry
 [no] indirect        + Create/Configure or Delete/Deconfigure indirect
                        next-hop for static-route-entry
 [no] next-hop        + Create/Configure or Delete/Deconfigure next-hop for
                        static-route-entry
 [no] tag             - Create/Configure or Delete/Deconfigure tag for
                        static-route-entry

Some SR OS CLI commands have multiple unnamed parameters. For example, the subrate csu-mode rate-step command has both a csu-mode parameter and a rate-step parameter that do not have leading keywords. SR OS uses a best-match algorithm to select which parts of the user input are intended to be used for each unnamed parameter. This best-match algorithm depends on the specific command.

In some cases, it is not possible for the algorithm to be 100% accurate, and SR OS may assign an unintended value to a parameter when two unnamed parameters have similar constraints and syntax. For example, the environment alias alias-name alias-command-name command may reverse the alias-name and alias-command-name parameters if the first parameter entered is more than 80 characters.

Using editing keystrokes

When entering a command, special keystrokes allow for editing of the command. The following table lists the command editing keystrokes.

Table 6. Command editing keystrokes
Editing action Keystrokes

Stop the current command

Ctrl-C

Delete current character

Ctrl-D

Delete text up to cursor

Ctrl-U

Delete text after cursor

Ctrl-K

Move to beginning of line

Ctrl-A

Move to end of line

Ctrl-E

Get prior command from history

Ctrl-P

Get next command from history

Ctrl-N

Move cursor left

Ctrl-B

Move cursor right

Ctrl-F

Move back one word

Alt-B or Esc+B

Move forward one word

Alt-F or Esc+F

Convert rest of word to uppercase

Alt-C or Esc+C

Convert rest of word to lowercase

Alt-L or Esc+L

Delete remainder of word

Alt-D or Esc+D

Delete word up to cursor

Ctrl-W

Transpose current and previous character

Ctrl-T

Enter command and return to operational root prompt

Ctrl-Z

Refresh input line

Ctrl-L

Entering absolute paths

CLI commands can be executed in any context by specifying the full path from the CLI root. To execute an out-of-context command, enter a forward slash (/) or backward slash (\) at the beginning of the command line. The commands are interpreted as absolute paths. Spaces between the slash and the first command return an error.

*A:cses-E11# configure router 
*A:cses-E11>config>router# interface system address 10.2.3.4 
*A:cses-E11>config>router# /admin save 
*A:cses-E11>config>router# \clear router interface 
*A:cses-E11>config>router# 

The ‟/” or ‟\” cannot be used as an absolute path at the beginning of the command string of the environment alias command. The command may change the current context depending on whether it is a leaf command. This is the same behavior the CLI performs when CLI commands are entered individually; for example:

*A:cses-E11# admin 
*A:cses-E11>admin# save

or

*A:cses-E11# admin save
*A:cses-E11# 

An absolute path command behaves in the same way as manually entering a series of command line instructions and parameters.

For example, beginning in an IES context service ID 4 (IES 4):

config>service>ies> /clear card 1

behaves in the way same as the following series of commands:

config>service>ies>exit all
clear card 1
configure service ies 4 (returns you to your starting point) 
config>service>ies

If the command takes you to a different context, the following occurs:

config>service>ies>/configure service vpls 5 create

becomes:

config>service>ies>exit all
configure service vpls 5 create
config>service>vpls>

Displaying the command history

The CLI maintains a history of the most recently entered commands. The history command shows the most recently entered CLI commands.

*A:cses-E11# history 
   1 environment terminal length 48 
   2 environment no create 
   3 show version 
   4 configure port 1/1/1 
   5 info 
   6 \configure router isis 
   7 \port 1/1/2
   8 con port 1/1/2
   9 \con port 1/1/2
  10 \configure router bgp 
  11 info 
  12 \configure system login-control 
  13 info 
  14 history 
  15 show version 
  16 history 
*A:cses-E11# !3

A:cses-E11# show version
TiMOS-B-0.0.I2016 both/i386 Nokia 7450 ESS Copyright (c) 2000-2016 Nokia
All rights reserved. All use subject to applicable license agreements.
Built on Sun Oct 12 20:01:13 PDT 2008 by builder in /rel0.0/I2016/panos/main
A:cses-E11# 

Entering numerical ranges

The SR OS CLI allows the use of a single numerical range as an argument in the command line. This range can be a set or a sequence of numbers, or a combination of both.

A set is a range of numerical values, from a minimum to a maximum, incremented by 1. For example:

configure service vpls [1..10] create customer 1

A sequence is a list of discrete integer elements, in any order. For example:

configure service vpls [1,2,3] no shutdown

A sequence can contain sets as well as integer elements. For example:

configure service vpls [4..6,7,8..10] no shutdown

For example, it is possible to shut down ports 1 through 10 on an XMA/MDA 1 in chassis slot 1. A port can be denoted by ‟slot/mda/port”, where slot is the slot number, mda is the XMA/MDA number and port is the port number. To shut down ports 1 through 10 on an XMA/MDA 1 in slot 1, the command is entered as follows:

configure port 1/1/[1..10] shutdown

Ctrl-C can be used to abort the execution of a range command.

CLI commands can contain ranges of hexadecimal values. This allows ranges to be used when working with data normally expressed in hexadecimal instead of decimal, such as IPv6 or MAC addresses. For example:

#config>service>vpls>sap$ static-mac aa:bb:[0x19..0x21]:dd:ee:ff create
#config>service>vpls>sap$ info
----------------------------------------------
                static-mac aa:bb:19:dd:ee:ff create
                static-mac aa:bb:1a:dd:ee:ff create
                static-mac aa:bb:1b:dd:ee:ff create
                static-mac aa:bb:1c:dd:ee:ff create
                static-mac aa:bb:1d:dd:ee:ff create
                static-mac aa:bb:1e:dd:ee:ff create
                static-mac aa:bb:1f:dd:ee:ff create
                static-mac aa:bb:20:dd:ee:ff create
                static-mac aa:bb:21:dd:ee:ff create
----------------------------------------------

A range can also be a reference to a previous range in the same command. This reference takes the form [$x], where x is an integer between 0 and 5. For example:

configure service vprn [11..20] router-id 10.20.[$0].1

This gives vprn 11 the router-id "10.20.11.1", vprn 12 the router-id "10.20.12.1", and so on.

Specifying a range in the CLI does have limitations. These limitations are summarized in the following table.

Table 7. CLI range use limitations
Limitation Description

Up to 6 ranges (including references) with 20 range elements in each range may be specified in a single command, and they may not combine to more than 1000 iterations of the command.

For example, ports on two adapter cards can be shut down in one command by using two ranges:

configure port 1/[1..2]/[1..10]

Ranges within quotation marks are interpreted literally.

In the CLI, enclosing a string in quotation marks (‟string”) causes the string to be treated literally and as a single parameter. For example, several commands in the CLI allow the configuration of a descriptive string. If the string is more than one word and includes spaces, it must be enclosed in quotation marks. A range that is enclosed in quotes is also treated literally. For example,

configure router interface "A[1..10]" no shutdown

creates a single router interface with the name ‟A[1..10]”. However, a command such as:

configure router interface A[1..10] no shutdown

creates 10 interfaces with names A1, A2 .. A10.

Command completion does not work when entering a range.

After entering a range in a CLI command, command and key completion, which normally occurs by pressing Tab or Spacebar, does not work. If the command line entered is correct and unambiguous, the command works properly; otherwise, an error is returned.

Using regular expressions in numerical ranges

The user can include a regular expression inside the numerical ranges of any clear, config, show, or tools CLI commands. The beginning and ending of the regular expression must be delimited with the "/" symbol.

SR OS performs the following steps:

  • auto-completes the command to get all the possible names

  • performs a match of the regular expression against all the names

  • executes the command for the names for which the match was successful

Note:

The order of execution is the same as the order in which the names are listed in the output display of the CLI info command or in the output display when you invoke the auto-complete function using Tab. If the execution of the command fails for one of the matching object names, the execution is aborted and the remaining matching object names are not processed.

For example, the following SR-TE LSP names are configured on the router:

*A:bkvm35# show router mpls sr-te-lsp
===============================================================================
MPLS SR-TE LSPs (Originating)
===============================================================================
LSP Name                       To              Tun      Protect     Adm    Opr
                                               Id       Path         
-------------------------------------------------------------------------------
sr-te-pce                      192.0.2.198     1        N/A         Up     Dwn  
RENO194_DET190_LSP1_Profile10  192.0.2.190     2        N/A         Up     Dwn  
RENO194_DET190_LSP3            192.0.2.190     3        N/A         Up     Dwn  
RENO194_ATL224_LSP1            192.0.2.224     4        N/A         Up     Dwn  
-------------------------------------------------------------------------------
LSPs : 4
===============================================================================

The following command displays the subset of all SR-TE LSPs with names that include the expression "LSP":

show router mpls sr-te-lsp [/LSP/]

The SR OS expands this command into the following individual commands:

show router mpls sr-te-lsp RENO194_DET190_LSP1_Profile10

show router mpls sr-te-lsp RENO194_DET190_LSP3

show router mpls sr-te-lsp RENO194_ATL224_LSP1

The output of the three show commands is displayed in the following example:

*A:bkvm35# show router mpls sr-te-lsp [/LSP/]
===============================================================================
MPLS SR-TE LSPs (Originating)
===============================================================================
LSP Name                           To               Tun     Protect   Adm  Opr
                                                    Id      Path
-------------------------------------------------------------------------------
RENO194_DET190_LSP1_Profile10      192.0.2.190      2       N/A       Up   Dwn
-------------------------------------------------------------------------------
LSPs : 1
===============================================================================
===============================================================================
MPLS SR-TE LSPs (Originating)
===============================================================================
LSP Name                           To               Tun     Protect   Adm  Opr
                                                    Id      Path
-------------------------------------------------------------------------------
RENO194_DET190_LSP3                192.0.2.190      3       N/A       Up   Dwn
-------------------------------------------------------------------------------
LSPs : 1
===============================================================================
===============================================================================
MPLS SR-TE LSPs (Originating)
===============================================================================
LSP Name                           To               Tun     Protect   Adm  Opr
                                                    Id      Path
-------------------------------------------------------------------------------
RENO194_ATL224_LSP1                192.0.2.224      4       N/A       Up   Dwn
-------------------------------------------------------------------------------
Regular expression symbols in a regular expression match operation

The user can use all the regular expression symbols listed in Regular expression symbols and Character class expressions inside the regular expression to match.

For example, the user can list all LSP names that begin with the string "RENO194_" followed by the string "ATL" as follows:

*A:bkvm35# show router mpls sr-te-lsp [/^RENO194_\['ATL'\]/]
===============================================================================
MPLS SR-TE LSPs (Originating)
===============================================================================
LSP Name                       To              Tun      Protect     Adm    Opr
                                               Id       Path         
-------------------------------------------------------------------------------
RENO194_ATL224_LSP1            38.120.48.224   4        N/A         Up     Dwn  
-------------------------------------------------------------------------------
LSPs : 1
===============================================================================
Note:

The following conventions are used in the previous example.

  • Use the character "^", which matches the start of the string, directly inside the regular expression to indicate a match at the start of the string. However, if you want to match it as a character, enter it as "\\^".

  • Use the range delimiter with the escape symbol in front "\[" inside the regular expression because the range delimiter encloses the regular expression.

The following table summarizes special rules governing the use of some of the regular expression symbols inside a regular expression match operation. Any symbol from Regular expression symbols or Character class expressions that is not listed in Rules governing regular expression symbols can be used directly inside a regular expression match operation.

Table 8. Rules governing regular expression symbols
String Description

?

[/\?/] if using as a regular expression and [/\\\?/] if using to match the character ?

[ ]

[/\[\]/] if using as a regular expression and [/\\\[\\\]/] if using to match the characters []

$

[/$/] if using as a regular expression and [/\\$/] if using to match the character $

\

[/\\\\/] if using to match the character \

/

[/\//] if using to match the character /

[/\'/] if using to match the character '

*

[/\\*/] if using to match the character *

.

[/\./] if using as a regular expression and [/\\\./] if using to match the character .

+

[/\\+/] if using to match the character +

,

[/\,/] if using to match the character ,

^

[/\\^/] if using to match the character ^

(

[/\\(/] if using to match the character (

)

[/\\)/] if using to match the character )

space

[/\ /] if using to match the character space

The SR OS does not support the combination of a partial string with a regular expression match operation.

For example, if the operator wants to display the SR-TE LSP names that begin with the string "RENO194_ATL", if part of the string is entered directly and the rest of the string is entered inside a regular expression, the command returns no match. The following example demonstrates the incorrect syntax:

*A:bkvm35# show router mpls sr-te-lsp RENO194_[/ATL/]

To obtain a match, the entire string must be inside the regular expression. The following example demonstrates the correct syntax for finding a match:

*A:bkvm35# show router mpls sr-te-lsp [/^RENO194_ATL/]
===============================================================================
MPLS SR-TE LSPs (Originating)
===============================================================================
LSP Name                       To              Tun      Protect     Adm    Opr
                                               Id       Path         
-------------------------------------------------------------------------------
RENO194_ATL224_LSP1            38.120.48.224   4        N/A         Up     Dwn  
-------------------------------------------------------------------------------
LSPs : 1
===============================================================================

Using the | match output modifier

The | match output modifier searches for a character string or pattern. When using the | match output modifier, the variables and attributes must be spelled correctly. The attributes follow the output modifier and must come before the expression or pattern. The following are examples of how to use the | match output modifier to complete different tasks:

  • Task: Capture all the lines that include ‟echo” and redirect the output to a file on the compact flash:

    admin display-config | match ‟echo” > cf1:\test\echo_list.txt

  • Task: Display all the lines that do not include ‟echo”:

    admin display-config | match invert-match ‟echo”

  • Task: Display the first match of ‟vpls” in the configuration file:

    admin display-config | match max-count 1 ‟vpls”

  • Task: Display everything in the configuration after finding the first instance of ‟interface”:

    admin display-config | match post-lines 999999 interface

  • Task: Display a count of the total number of lines of output instead of displaying the output itself:

    admin display-config | match interface | count

Command syntax:

match pattern context {parents | children | all} [ignore-case] [max-count lines-count] [expression]

match pattern [ignore-case] [invert-match] [pre-lines pre-lines] [post-lines lines-count] [max-count lines-count] [expression]

where:

pattern         string or regular expression
context         keyword:  display context associated with the matching line
parents         keyword:  display parent context information
children        keyword:  display child context information
all             keyword:  display both parent and child context information
ignore-case     keyword
max-count       keyword:  display only a specific number of instances of matching 
                          lines
lines-count     1 — 2147483647
expression      keyword:  pattern is interpreted as a regular expression
invert-match    keyword
pre-lines       keyword:  display some lines prior to the matching line
pre-lines       0 — 100
post-lines      keyword:  display some lines after the matching line
lines-count     1 — 2147483647

For example:

A:Dut-C# show log log-id 98 | match ignore-case "sdp bind"
"Status of SDP Bind 101:1002 in service 1001 (customer 1) changed to admin=up oper=u
p flags="
"Processing of a SDP state change event is finished and the status of all affected S
DP Bindings on SDP 101 has been updated."


A:Dut-C# show log log-id 98 | match max-count 1 "service 1001"
"Status of service 1001 (customer 1) changed to administrative state: up, 
operational state: up"

A:Dut-C# admin display-config | match post-lines 5 max-
count 2 expression "OSPF.*Config"
echo "OSPFv2 Configuration"
#--------------------------------------------------
        ospf
            timers
                spf-wait 1000 1000 1000
            exit
echo "OSPFv2 (Inst: 1) Configuration"
#--------------------------------------------------
        ospf 1
            asbr
            router-id 10.0.0.1
            export "testall"
*A:Dut# admin display-config | match debug_mirror
            profile "debug_mirror"


*A:Dut# admin display-config | match context parent debug_mirror
#--------------------------------------------------
    system
        security
            profile "debug_mirror"


*A:Dut# admin display-config | match context all debug_mirror
#--------------------------------------------------
    system
        security
            profile "debug_mirror"
                default-action deny-all
                entry 10
                exit


*A:Dut# show log event-control | match ignore-case pre-lines 10 SyncStatus
L  2016 tmnxLogOnlyEventThrottled        MA  gen          0           0
MCPATH:
   2005 tmnxMcPathSrcGrpBlackHole        MI  thr          0           0
   2006 tmnxMcPathSrcGrpBlackHoleCleared MI  thr          0           0
   2007 tmnxMcPathAvailBwLimitExceeded   MI  thr          0           0
   2008 tmnxMcPathAvailBwLimitCleared    MI  thr          0           0
MC_REDUNDANCY:
   2001 tmnxMcRedundancyPeerStateChanged WA  gen          0           0
   2002 tmnxMcRedundancyMismatchDetected WA  gen          0           0
   2003 tmnxMcRedundancyMismatchResolved WA  gen          0           0
   2004 tmnxMcPeerSyncStatusChanged      WA  gen          0           0

The following table describes regular expression symbols and their interpretation (similar to what is used for route policy regexp matching). Character class expressions describes character class expressions.

Table 9. Regular expression symbols
String Description

.

Matches any single character

[ ]

Matches a single character that is contained within the brackets

[abc] matches ‟a”, ‟b”, or ‟c”

[a-z] matches any lowercase letter

[A-Z] matches any uppercase letter

[0-9] matches any number

[^ ]

Matches a single character that is not contained within the brackets

[^abc] matches any character other than ‟a”, ‟b”, or ‟c”

[^a-z] matches any single character that is not a lowercase letter

^

Matches the start of the line (or any line, when applied in multiline mode)

$

Matches the end of the line (or any line, when applied in multiline mode)

()

Defines a ‟marked subexpression”

Every matched instance will be available to the next command as a variable

*

A single character expression followed by ‟*” matches zero or more copies of the expression

{m,n}

Matches least m and at most n repetitions of the term

{m}

Matches exactly m repetitions of the term

{m,}

Matches m or more repetitions of the term

?

The preceding item is optional and matched at most once

+

The preceding item is matched one or more times

-

Used between start and end of a range

\

An escape character to indicate that the following character is a match criteria and not a grouping delimiter

Table 10. Character class expressions
Character class Characters matched1 Description

[:alnum:]

‛ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789’

Alphanumeric characters

[:alpha:]

‛ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz’

Alphabetic characters

[:blank:]

‛ \t’

Spacebar and Tab

[:cntrl:]

‛\007\b\t\n\v\f\r\1\2\3\4\5\6\16\17\20 \21\22\23\24\25\26\27\30 \31\32\33\34\35\36\37\177’

Control characters

[:digit:]

‛0123456789’

Digits

[:graph:]

‛ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789 !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~’

Visible characters

[:lower:]

‛abcdefghijklmnopqrstuvwxyz’

Lowercase letters

[:print:]

‛ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ ’

Visible characters and the Space character

[:punct:]

‛!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~’

Punctuation characters

[:space:]

‛\t\n\v\f\r ‛

Whitespace (blank) characters

[:upper:]

‛ABCDEFGHIJKLMNOPQRSTUVWXYZ’

Uppercase letters

[:xdigit:]

‛0123456789ABCDEFabcdef’

Hexadecimal digits

Character class expressions must be enclosed within brackets. The expression [[:digit:]] is treated as a regular expression containing the character class ‟digit”, while [:digit:] is treated as a regular expression matching ‟:”, ‟d”, ‟i”, ‟g”, or ‟t”.

Using the | count output modifier

The | count output modifier displays a count of the number of lines that would have otherwise been displayed. The | count output modifier is particularly useful when used in conjunction with the | match output modifier in order to count the number of output lines that match a specified pattern.

The following example shows usage of the | count output modifier.

Using the | count output modifier

*A:dut-c# show service service-using vprn

===============================================================================
Services [vprn]
===============================================================================
ServiceId    Type      Adm  Opr  CustomerId Service Name
-------------------------------------------------------------------------------
1            VPRN      Down Down 1
44           VPRN      Up   Up   1
100          VPRN      Down Down 1
102          VPRN      Up   Up   1
235          VPRN      Down Down 1
1000         VPRN      Down Down 1000
-------------------------------------------------------------------------------
Matching Services : 6
-------------------------------------------------------------------------------
===============================================================================
*A:dut-c# show service service-using vprn | match Down | count
Count: 4 lines
*A:dut-c#

Using the | reverse-dns output modifier

The | reverse-dns output modifier performs a reverse DNS lookup on any IPv4 or IPv6 address in the input. The result of the lookup is inserted as the next line in the output on each line where an IP address is identified. If no match is found, no additional output is printed. If the output line is more than 80 characters, the line is truncated.

The following example shows usage of the | reverse-dns output modifier.

Using the | reverse-dns output modifier

A:node-2# ping 10.184.216.34 | reverse-dns
PING 10.184.216.34 56 data bytes
(10.184.216.34) www.example.com
64 bytes from 10.184.216.34: icmp_seq=1 ttl=61 time=82.4ms.
64 bytes from 10.184.216.34: icmp_seq=2 ttl=61 time=82.5ms.
64 bytes from 10.184.216.34: icmp_seq=3 ttl=61 time=82.4ms.
64 bytes from 10.184.216.34: icmp_seq=4 ttl=61 time=82.3ms.
64 bytes from 10.184.216.34: icmp_seq=5 ttl=61 time=82.2ms.
---- 10.184.216.34 PING Statistics ----
(10.184.216.34) www.example.com
5 packets transmitted, 5 packets received, 0.00% packet loss
round-trip min = 82.2ms, avg = 82.4ms, max = 82.5ms, stddev = 0.122ms

Redirecting output to a file

SR OS supports output redirection (>), which allows the operator to store the output of a CLI command as a local or remote file.

For example:

‛ping <customer_ip> > cf3cf1:/ping/result.txt’
‛ping <customer_ip> > ftp://ron@ftp.nokia.com/ping/result.txt’

In some cases, only part of the output might be applicable. The | match and output redirection commands can be combined:

ping 10.0.0.1 | match expression ‟time.[[:digit:]]+” > cf3cf1:/ping/time.txt

This records only the RTT portion (including the word ‟time”).

Configuration rollback

The Configuration Rollback feature provides the ability to undo configurations and revert to previous router configuration states while minimizing impacts to services.

This feature gives the operator better control and visibility over the router configurations and reduces operational risk while increasing flexibility and providing powerful recovery options.

Configuration Rollback is useful in cases where configuration changes are made but the operator later decides not to keep the changes (for example, experimentation or when problems are identified in the configuration during actual network operation).

The advantages of this feature include the following.

  • Changes made to the router configuration are performed with minimal impact on services being provided by the SR because the router does not need to be rebooted.

  • There is no impact in areas of the configuration that did not change.

With the rollback feature, the operator can smoothly revert to previous configurations.

Configuration parameters that are changed or items that the changed configuration have dependencies on are removed (revert to default) and the previous values are restored, which may briefly impact services in changed areas).

A history of changes is preserved using checkpoint IDs, which allow rollback to different points, as well as examination of changes made, as shown in the following figure.

Figure 1. Rollback operation

Feature behavior

The following list describes detailed behavior of the rollback feature, including the applicable CLI commands.

  • The user can create a rollback checkpoint and later revert to this checkpoint with minimal impact to services.

    admin>rollback# save [comment comment-string]

    comment-string: a comment associated with the checkpoint, maximum 255 characters

  • Rollback checkpoints include all current operationally active configurations:

    • changes from direct CLI commands in the configuration branch

    • SNMP sets

  • Rollback checkpoints do not include BOF configurations. The BOF file and BOF configuration are not part of a rollback save or rollback. A rollback does not change the BOF configuration. The BOF contains basic information for the node and does not change frequently; changes are mostly made during initial commissioning of the node.

  • A rollback save feature can be automatically executed (for example, scheduled monthly) using the CRON facility of SR OS.

  • The latest rollback checkpoint file uses the suffix ‟.rb”. The next latest rollback checkpoint file has the suffix ‟.rb.1”, the next oldest has the suffix ‟rb.2”, and so on.

    file-url.rb <--- latest rollback file

    file-url.rb.1

    file-url.rb.9 <--- oldest rollback file

  • When a rollback save is executed, the system shifts the file suffix of all the previous checkpoints by 1 (new ID = old ID + 1). If there are already as many checkpoint files as the maximum number supported, the last checkpoint file is deleted.

  • The maximum number of rollback checkpoints is configurable and defaults to 10, which includes the latest file and files 1 through 9.

  • The locations and names of the rollback checkpoint files are configurable to be local (on the compact flash) or remote. The file-url must contain a path/directory and filename with no suffix. The .rb suffix for rollback checkpoint files is automatically appended to the rollback checkpoint files.

    config>system>rollback# rollback-location file-url

  • There is no default rollback location. If a rollback location is not specified, or it is cleared using no rollback-location, and a rollback save is attempted, the rollback save fails and returns an error message.

  • The entire set of rollback checkpoint files can be copied from the active CPM CF to the standby CPM CF. This synchronization is done using the following command:

    admin>redundancy# rollback-sync

  • The operator can enable an automatic synchronization of rollback checkpoint files between the active CPM and standby CPM. When this automatic synchronization is enabled, a rollback save causes the new checkpoint file to be saved to both the active and standby CPMs. The suffixes of the old checkpoint files on both active and standby CPMs are incremented.

    Automatic synchronization only causes the new checkpoint file to be copied to both CFs. The older checkpoint files are not automatically copied from active to standby but can be copied manually with admin redundancy rollback-sync.

  • The config>redundancy>synchronize {boot-env | config} and admin>redundancy>synchronize {boot-env | config} commands do not apply to rollback checkpoint files. These commands do not manually or automatically synchronize rollback checkpoint files. The dedicated rollback-sync commands must be used to synchronize rollback checkpoint files.

  • Rollback files can be deleted using a dedicated rollback checkpoint deletion command.

    admin>rollback# delete {latest-rb | checkpoint-id}

    • Deleting a rollback checkpoint causes the suffixes to be adjusted (decremented) for all checkpoints older that the one that was deleted in order to close the ‟hole” in the list of checkpoint files and create room to create another checkpoint.

    • If config>redundancy>rollback-sync is enabled, a rollback delete also deletes the equivalent checkpoint on the standby CF and shuffles the suffixes on the standby CF.

    • If an operator manually deletes a rollback checkpoint file using file delete, the suffixes of the checkpoint files are not shuffled, nor is the equivalent checkpoint file deleted from the standby CF. This manual deletion creates a ‟hole” in the checkpoint file list until enough new checkpoints have been created to roll the ‟hole” off the end of the list.

  • The following figure shows how a configuration is rolled back to a previous configuration (a saved rollback checkpoint). The previous configuration is loaded and takes operational effect.

    admin>rollback# revert [latest-rb | checkpoint-id]

    Figure 2. Configuration rollback
  • A rollback revert does not affect the currently stored rollback checkpoint files; files are not deleted or renumbered. This means that if an operator issues the command rollback revert 3 and then issues the rollback save command, the resulting rollback checkpoint files file-url.rb and file-url.rb.4 contain the same rollback state/configuration.

  • The boot-good-exec or boot-bad-exec command is not automatically executed after a rollback.

  • Impacts to the running services are minimized during a rollback.

    • There is no impact in areas of the configuration that did not change.

    • Configuration parameters that are changed or items that the changed configuration has dependencies on are removed (revert to default) and the previous values are restored, which may briefly impact services. The following are examples of service impact.

      • If the currently active configuration contains configure port 5/1/1 dwdm tdcm dispersion -1000 and the rollback checkpoint contains configure port 5/1/1 dwdm tdcm dispersion -1010, the operational dispersion transitions from -1000 to 0 and then back to -1010 for port 5/1/1, which causes a traffic interruption.
      • If changing neighbor 1 of an MC-APS port, the port must be configured as no neighbor and then configured as neighbor 2. Moving through the no neighbor intermediate state requires the working and protection circuits to be torn down and rebuilt. This impacts the 7450 ESS and 7750 SR.
  • A rollback undoes any SNMP sets or direct CLI configuration commands that occur after the creation of the last checkpoint.

  • When a node is processing a rollback revert, both CLI commands from other users and SNMP commands continue to be processed. The only commands that are blocked during a rollback revert are other rollback commands, including revert, save, and compare. Only one rollback command can be executing at a time on a node.

  • Commands are available to view and compare the various rollback checkpoints to current operating and candidate configurations.

  • Rollback checkpoint files are not guaranteed to be in any particular format. They are not interchangeable with normal configuration files or executable scripts. A normal configuration file from an admin save cannot be renamed as a rollback checkpoint and then referenced for a rollback revert operation. Only rollback checkpoint files generated with rollback save can be used for rollback revert operations.

  • If a hardware change is made after a rollback save, then:

    • a rollback can be executed as long as the hardware change was an addition of hardware to the node (for example, a new card or IOM was installed into a previously empty slot)

    • a rollback is not guaranteed to work if hardware was removed or changed (for example, an XCM/IOM was removed, or an XMA/MDA was swapped for a different XMA/MDA type)
  • Rollback across a change to the following parameters is not supported:

    • chassis-mode
    • configure isa application-assurance-group minimum-isa-generation
  • Rollback is supported even after an admin reboot is performed or the primary configuration in the BOF is changed and an admin reboot is performed. The admin reboot command does not ‟break the chain” for rollback.

  • Lawful intercept configuration under the config>li branch is not affected by a rollback or rescue. LI configuration is not saved in the rollback checkpoint or rescue file, and a rollback revert does not affect any configuration under the config>li branch.
  • Any configuration or state change performed under the debug branch of the CLI is not saved in the rollback checkpoint file or impacted by a rollback.

  • Rollbacks to a checkpoint created in a more recent release are not supported (for example, a node running in 9.0r5 cannot roll back to a checkpoint created in 9.0r7).
  • The following list captures some side effects and specific behaviors of a rollback revert. Some of these side effects are not related purely to configuration, that is, in the CLI configuration branch, and may have interactions with tools commands, RADIUS, and so on.

    • SAA jobs that are running when a rollback revert is initiated, and need configuration changes due to the rollback, are stopped. If the SAA job is a continuous type, then it is restarted as part of the rollback revert after the configuration changes have been applied (just as if the operator had typed no shutdown for the continuous SAA job). Non-continuous SAA jobs that were modified by the rollback would need to be manually restarted if they need to be run again.

    • If max-nbr-mac-addr is reduced as part of the revert and the number of MAC addresses in the forwarding database is greater than the max-nbr-mac-addr, the rollback is aborted before any actions are taken and an informative error message is provided. The operator must take actions to remove the MAC addresses if they wish to proceed with the rollback.
    • If active subscribers or subscriber hosts or DHCP lease states are present, some associated configuration changes may be blocked, just as those same changes would be blocked if an operator tried to make them using CLI.

    • When trying to delete an SLA profile being used by active subscriber hosts, or trying to change a NAT policy in a subscriber profile, if certain configuration changes associated with the hosts or lease states are required as part of the rollback but those changes are blocked, then for each blocked configuration item a warning is printed, that particular configuration item is not changed, and the rollback continues. This is supported on the 7450 ESS and 7750 SR.

    • After a multi-chassis peer shutdown or if configuration changes have been made that affect the contents of the distributed database (for example, synchronization tag creation or deletion), further configuration changes related to that peer may be temporarily refused. The duration of the temporary configuration freeze depends on the size of the distributed database. A rollback attempting to make those refused configuration changes fails and an error message is provided to the CLI user.

    • If a force-switchover command (for example, tools perform service id 1 endpoint "x" force-switchover spoke-sdp-fec 1) has been applied to a spoke-sdp-fec of a dynamic multi-segment pseudowire, and a rollback revert needs to change the admin state of the spoke-sdp-fec (for example, to modify spoke-sdp-fec parameters that may be dependent on the admin state), the rollback revert automatically removes the force-switchover and the node reverts to whatever is the best spoke SDP in the redundant set.
    • Rollback impacts the configuration state of the router, and as with normal operator CLI or SNMP configuration changes, additional actions or steps may need to occur before certain configuration changes take operational effect.

      Configuration changes that require a manual shutdown and then no shutdown in order to take operational effect also need this manual shutdown/no shutdown in order to take operational effect after a rollback if the rollback changes those configuration items. Some examples include the following.

      • Changes to autonomous system or confederation values require a BGP shutdown/no shutdown command.

      • Changes to VPRN max-routes require a shutdown/no shutdown command on the VPRN service.

      • Changes to OSPF or IS-IS export-limit require a shutdown/no shutdown command on OSPF or IS-IS.

      • For configuration changes to an MSAP policy that normally require a tools perform subscriber-mgmt eval-msap command to take operational effect on subscribers that are already active, if a rollback changes the MSAP policy configuration, the operator must run the eval-msap tools command to have the changes applied to the active subscribers.
    • Any uncommitted changes (for example, the begin command was entered and some changes were made, but the commit command was never entered) in the following areas are lost or cleared when a rollback revert is initiated:

      • config>app-assure>group policy
      • config>router>policy-options

      • config>system>sync-if-timing

  • Some card and mda commands require a reboot, removal, or rebuild of an entire card or XMA/MDA. When these commands need to be executed as part of a rollback, the impacted cards and MDAs are listed in a warning and the operator is prompted with a single y/n prompt to proceed. This prompt will not occur for a rollback initiated via SNMP or if the operator uses the now keyword with the rollback revert command. Some examples of card and mda commands that may cause a prompt are:

    • config>card>card-type

    • config>card>mda

    • config>card>mda>mda-type

  • Although the use of the Ctrl-C key combination is not recommended during a rollback revert, it is supported via CLI or SNMP. Interrupting a rollback revert may leave the router in a state that is not necessarily between the old active configuration and the rollback checkpoint, as the rollback processing may have been in the middle of tearing things down or rebuilding configurations. A strong warning is issued in this case to indicate that the operator must examine the configuration and potentially issue another rollback revert to return to a known and coherent configuration.

  • An HA CPM switchover during a rollback revert causes the rollback operation to abort. The newly active CPM has an indeterminate configuration. When an HA switchover occurs during a rollback or within a few seconds of a rollback completing, the operator is advised to repeat the rollback revert operation to the same checkpoint.

  • A rollback revert operation does not check authorization of each command that is applied during the revert. Permission to execute the revert operation, that is, authorization to execute the admin rollback revert command, should only be given to users who are allowed to initiate a rollback revert. It is generally recommended that only system administrators be allowed access to the file system where the rollback files are stored so that they cannot be manually edited.

Rollback and SNMP

The SR OS has SNMP support for rollback status and control. See the TIMETRA-SYSTEM-MIB for details (for example, items such as tmnxSysRollbackStarted).

When the router is doing a rollback revert, SNMP managers see a tmnxSysRollbackStarted trap, then a rapid set of ‟config change” traps, and then finally, the tmnxSysRollbackStatusChange trap.

During the period when a router is processing a rollback revert, both CLI commands from other users and SNMP commands continue to be processed.

Rescue configuration

A special rescue configuration checkpoint can be created that an operator can revert to at any time. The rescue configuration has its own keyword (rescue) and does not use the same rolling suffix indices as the normal rollback checkpoints. This allows the operator to easily return to the rescue configuration state without having to consider a checkpoint index, and ensures that the rescue checkpoint is always available and does not roll off the bottom of the list of checkpoints.

The operator should define a basic rescue configuration that is known to work and give appropriate management access to the node.

The location and filename of the rescue file are configurable. The SR OS appends the .rc suffix to the specified rescue filename.

Operational guidelines

The following points offer some operational guidance on the use of rollback.

  • The admin save and admin rollback save commands should be performed periodically.

  • The admin save command can be used to back up a complete configuration file that can be used during router reboot, with the following considerations:

    • used with a reboot as a last resort

    • performed after any major hardware changes or major service changes

    • performed after any software upgrade

  • The admin rollback save command can be used to create a rollback checkpoint as follows:

    • to be used for intermediate checkpoints that can be recovered with minimal impact to services

    • to be performed each time a moderate number of configuration changes have been made

    • to be performed after any hardware changes

    • to be performed after any software upgrade

    • to be scheduled with CRON (for example, once every one or two weeks)

  • A new admin rollback save rescue must be created when hardware is changed.

  • Rollback checkpoint files are not editable, or compatible or interchangeable with configuration files generated with admin save.

  • The repeated use of the admin rollback save, admin rollback delete, and admin rollback revert commands over the course of weeks or months is not recommended without also executing an occasional admin save. In a serious situation, use one of the saved configurations as the primary configuration for an admin reboot.

  • For a software upgrade, it is recommended that a rollback checkpoint be created using admin rollback save in addition to saving the configuration with admin save, after an upgrade has been performed and the system is operating as expected. This ensures that a good checkpoint that is fully compatible with the new release is available at a point shortly after the upgrade.

  • An operator can create a set of rollback checkpoints to support busy or quiet days or weekends or weekdays and use CRON to shift between them.

  • It is beneficial to create a rollback checkpoint before a rollback revert is initiated, especially if significant configuration changes have been applied since the last checkpoint was created. If the rollback is especially significant, that is, there are a lot of major changes, it is also a good practice to perform an admin save in case a full reboot is required to recover from an issue.

  • A rollback failure may occur in some limited cases where the node needs a long time to complete one of the resulting configuration changes. If a rollback (for example, rollback revert 5) fails during execution, it should be attempted again. The second attempt typically completes the remaining configuration changes required to fully revert to the desired checkpoint.

  • When a new backup CPM is commissioned, the user executes the admin redundancy rollback-sync command to copy the entire set of rollback files from the active CPM CF to the new standby CPM CF. If the operator wants the system to automatically copy new rollback checkpoints to both CFs whenever a new checkpoint is created, the configure redundancy rollback-sync command should be enabled.

  • An HA CPM switchover during a rollback revert causes the rollback operation to abort. The newly active CPM has an indeterminate configuration. A log event is created in this case to warn the operator. When an HA switchover occurs during a rollback or within a few seconds of a rollback completing, the operator is advised to repeat the rollback revert operation to the same checkpoint.

  • A rollback checkpoint stores the rollback location and the local-max-checkpoint and remote-max-checkpoint values, and it is possible that a rollback revert operation may change those values. If an operator changes the local-max-checkpoint or remote-max-checkpoint values, it is recommended that all the existing checkpoints be deleted to prevent a subsequent rollback revert from changing the maximum values to any of the previous values.

  • If a warning prompt (y/n) is displayed when a rollback revert is initiated, it is highly recommended that the operator respond no to the warning prompt the first time, save a rollback checkpoint before attempting this rollback revert, execute the revert again, and respond yes. If the rollback encounters problems, a revert to the saved checkpoint can be used to return to the initial configuration state.

Transactional configuration

Transactional configuration allows an operator to edit a candidate configuration (a set of configuration changes) without causing operational changes in the router (the active or operational configuration). When the candidate configuration is complete, the operator can explicitly commit the changes to make the entire new configuration become active.

Transactional configuration gives the operator better control and visibility over their router configurations and reduces operational risk while increasing flexibility.

The transactional configuration and configuration rollback functions combine to provide the operational model depicted in the following figure.

Figure 3. Router configuration with rollback and transactions

Basic operation

In order to edit the candidate configuration, the operator must first enter the candidate edit mode (edit-cfg) with the candidate>edit command. The operator can enter and quit the configuration mode as many times as they wish before finally committing the candidate configuration.

In edit-cfg mode, the operator builds a set of candidate configuration changes using the same CLI tree as the standard line-by-line, non-transactional configuration. Tab completion and keyword syntax checking is available.

Just as there is a single operational active configuration that can be modified simultaneously by multiple users in the SR OS, there is also a single global candidate configuration instance. All users make changes in the same global candidate configuration, and a commit operation by any user commits the changes made by all users.

Users can exclusively create a candidate configuration by blocking other users and sessions of the same user from entering edit-cfg mode by specifying the exclusive parameter. The config>system>management-interface>cli>classic-cli>allow-immediate command can be used to enforce the use of candidate configuration, instead of allowing immediate line-by-line configuration changes.

If a commit operation is successful, all of the candidate changes take operational effect and the candidate is cleared. If there is an error in the processing of the commit, or a commit confirmed is not confirmed and an auto-revert occurs, the router returns to a configuration state with none of the candidate changes applied. The operator can then continue editing the candidate and try a commit later.

All commands in the candidate configuration must be in the correct order for a commit to be successful. Configuration that depends on other candidate objects must be placed after those objects in the candidate. A set of candidate editing commands (copy, insert, and so on) are available to correct and reorder the candidate configuration.

The edit-cfg mode is primarily intended for building a candidate configuration while navigating the configure branch of the CLI. Many CLI commands in branches other than configure are supported while in edit-cfg mode, but access to some CLI branches and commands are blocked, including:

  • exec command

  • enable-admin command

  • enable-dynamic-services-config command

  • admin branch

  • bof branch

  • debug branch

  • tools branch

The candidate configuration can be saved to a file and subsequently loaded into a candidate configuration. A saved candidate is similar to, but not the same as, an SR OS configuration file generated with an admin save command. The saved candidate cannot be used in general as a configuration file and may not exec without failures.

There is no SNMP access to the candidate configuration and no SNMP management of candidates, although any configuration changes made using transactional configuration are reported via the standard SR OS SNMP change traps and basic candidate status information is available via SNMP.

A commit may fail for a number of reasons, including:

  • misordering: the candidate configuration has changes that are not in the correct order, that is, an object is referred to before it is actually created

  • invalid options and combinations: although many syntax errors are eliminated during the candidate editing process, the candidate configuration may contain combinations of configurations and options that are not valid and are rejected when the SR OS attempts to have them take operational effect

  • out of resources: the application of the candidate may exhaust system resources, such as queue resources

Error messages are provided for commit failures to help the operator take the necessary actions to correct the candidate.

Standard line-by-line, non-transactional CLI and SNMP commands are not blocked during the creation or editing of a candidate or the processing of a commit. These commands take immediate operational effect when Enter is pressed.

Transactions and rollback

By default, the SR OS automatically creates a new rollback checkpoint after a commit operation. The rollback checkpoint includes the new configuration changes made by the commit. An optional no-checkpoint keyword can be used to prevent the auto-creation of a rollback checkpoint after a commit. If the commit fails, no new rollback checkpoint is created.

When the commit confirmed option is used, a rollback checkpoint is created after the processing of the commit and exists whether the commit is automatically reverted or not.

Transactional configuration relies on the rollback mechanism to operate. Any commands and configurations that are not supported in a rollback revert are also not supported in edit-cfg mode; for example, changes to chassis-mode.

Authorization

Authorization works transparently in edit-cfg mode and no unique or new local profile or TACACS+ permissions rules are required other than allowing access to the candidate branch. For example, if an operator has permission to access the configure filter context, they automatically also have access to the configure filter context when in edit-cfg mode.

If the operator’s profile allows access to the candidate load and save commands, the operations load and save only those items that the user is authorized to access.

The candidate view only displays the items that the user is authorized to access.

The candidate editing commands (such as adding lines, removing lines, and delete operations) only allow operations on items that the user is authorized to access.

The candidate commit and discard commands, along with admin rollback revert, operate on the entire candidate and impact all items; authorization does not apply.

1 Characters matching the character class are delimited by single quotation marks (‛).