2. CLI usage
This chapter provides information about using the command-line interface (CLI).
2.1. CLI structure
Nokia’s Operating System (OS) CLI is a command-driven interface accessible through the console, Telnet and secure shell (SSH). The CLI can be used for configuration and management of routers.
The CLI command tree is a hierarchical inverted tree. At the highest level is the ROOT level. Below this level are other tree levels with the major command groups; for example, configuration commands and show commands are levels below ROOT.
The CLI is organized so 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.
2.2. Navigating in the CLI
This section provides additional navigational and CLI syntax information.
2.2.1. CLI contexts
Use the CLI to access, configure, and manage Nokia 7210 SAS devices. 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 you initially enter a CLI session, you are in the ROOT context. Navigate to another level by entering the name of successively lower contexts. For example, enter either the configure or show commands at the ROOT context to navigate to the config or show context, respectively. For example, at the command prompt, enter config. The active context displays in the command prompt.
In a CLI context, you can enter commands at that context level by entering the text. It is also possible to include a command in a lower context as long as the command is formatted in the correct command and parameter syntax.
The following example shows two methods to navigate to a service SAP ingress level:
Method 1:
Method 2:
The CLI returns an error message when the syntax is incorrect.
2.2.2. Basic CLI commands
The console control commands are the commands that are used for navigating within the CLI and displaying information about the console session. Most of these commands are implemented as global commands. They can be entered at any level in the CLI hierarchy with the exception of the password command, which must be entered at the ROOT level. The console control commands are described in the following table.
Table 5: Console control commands
Command | Description |
<Ctrl-c> | Aborts the pending command. |
<Ctrl-z> | Terminates the pending command line and returns to the ROOT context. |
back | Navigates the user to the parent context. |
clear | Clears statistics for a specified entity or clears and resets the entity. |
echo | Echos the text that is typed in. Primary use is to display messages to the screen within an exec file. |
exec | Executes the contents of a text file as if they were CLI commands entered at the console. |
exit | Returns the user to the previous higher context. |
exit all | Returns the user to the ROOT context. |
help ? | Displays help in the CLI. |
history | Displays a list of the most recently entered commands. |
info | Displays the running configuration for a configuration context. |
logout | Terminates the CLI session. |
oam | Provides OAM test suite options. See the OAM section of the 7210 SAS-Mxp, R6, R12, S, Sx, T OAM and Diagnostics Guide. |
password | Changes the user CLI login password. The password can only be changed at the ROOT level. |
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 one second or for the specified number of seconds. Primary use is to introduce a pause within the execution of an exec file. |
ssh | Opens a secure shell connection to a host. |
telnet | Telnet to a host. |
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. |
The list of all system global commands is displayed by entering help globals in the CLI. For example:
The following table describes command syntax symbols.
Table 6: Command syntax symbols
Symbol | Description |
| | A vertical line indicates that one of the parameters within the brackets or braces is required. tcp-ack {true|false} |
[ ] | Brackets indicate optional parameters. redirects [number seconds] |
< > | Angle brackets indicate that you must enter text based on the parameter inside the brackets. interface <interface-name> |
{ } | Braces indicate that one of the parameters must be selected. default-action {drop|forward} |
[{ }] | Braces within square brackets indicates that you must choose one of the optional parameters.
|
Bold | Commands in bold indicate commands and keywords. |
Italic | Commands in italics indicate command options. |
2.2.3. CLI environment commands
The CLI environment commands are found in the root>environment context of the CLI tree and controls session preferences for a single CLI session. The CLI environment commands are described in the following table.
Table 7: 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. |
more | Configures whether CLI output should 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. |
terminal | Configures the terminal screen length for the current CLI session. |
time-display | Specifies whether time should be displayed in local time or UTC. |
2.2.4. CLI monitor commands
Monitor commands display specified statistical information related to the monitor subject (such as filter, port, QoS, router, service) at a configurable interval until a count is reached. The CLI monitor commands are found in the root>monitor context of the CLI tree.
The monitor command output displays a snapshot of the current statistics. The output display refreshes with subsequent statistical information at each configured interval and is displayed as a delta to the previous display.
The <Ctrl-c> keystroke interrupts a monitoring process. Monitor command configurations cannot be saved. You must enter the command for each monitoring session. Note that if the maximum limits are configured, you can monitor the statistical information for a maximum of 60 * 999 sec ~ 1000 minutes.
The CLI monitor command are described in the following table.
Table 8: CLI monitor command contexts
Command | Description |
filter | Enables IP, IPv6 and MAC filter monitoring at a configurable interval until that count is reached. |
lag | Enables Link Aggregation Group (LAG) monitoring to display statistics for individual port members and the LAG. |
port | Enables port traffic monitoring. The specified port(s) statistical information displays at the configured interval until the configured count is reached. |
router | Enables virtual router instance monitoring at a configurable interval until that count is reached. |
service | Monitors commands for a particular service. |
2.3. Getting help in the CLI
The help system commands and the ? key display different types of help in the CLI. The following table describes the different help commands.
Table 9: Online help commands
Command | Description |
help ? | List all commands in the current context. |
string ? | List all commands available in the current context that start with string. |
command ? | Displays the command’s syntax and associated keywords. |
command keyword ? | List the associated arguments for keyword in command. |
string<Tab> | Complete a partial command name (auto-completion) or list available commands that match string. |
The tree and tree detail system commands are help commands useful when searching for a command in a lower-level context.
The following table shows a partial list of the tree and tree detail command output entered at the config level.
Table 10: Output from tree command
A:ALU-7210>config# tree configure +---card | +---card-type | +---mda | | +---access | | +---mda-type | | +---network | | +---shutdown | +---shutdown +---cron | +---action | | +---expire-time | | +---lifetime | | +---max-completed | | +---results | | +---script | | +---shutdown | +---schedule | | +---action | | +---count | | +---day-of-month | | +---description | | +---end-time | | +---hour | | +---interval | | +---minute | | +---month | | +---shutdown | | +---type | | +---weekday | +---script | | +---description | | +---location | | +---shutdown | +---time-range | | +---absolute | | +---daily | | +---description | | +---weekdays | | +---weekend | | +---weekly | +---tod-suite | | +---description | | +---egress | | | +---filter | | | +---qos | | | +---scheduler-policy | | +---ingress | | | +---filter | | | +---qos | | | +---scheduler-policy +---dot1ag | +---domain | | +---association |... | *A:ALA-12>config# tree detail configure +---card <slot-number> | no card <slot-number> | +---card-type <card-type> | | no card-type | +---mda <mda-slot> | | no mda <mda-slot> | | +---access | | +---mda-type <mda-type> | | | no mda-type | | +---network | | +---no shutdown | | | shutdown | +---no shutdown | | shutdown +---cron | +---action <action-name> [owner <action-owner>] | | no action <action-name> [owner <action-owner>] | | +---expire-time {<seconds>|forever} | | +---lifetime {<seconds>|forever} | | +---max-completed <unsigned> | | +---no results | | | results <file-url> | | +---no script | | | script <script-name> [owner <script-owner>] | | +---no shutdown | | | shutdown | +---no schedule <schedule-name> [owner <schedule-owner>] | | schedule <schedule-name> [owner <schedule-owner>] | | +---action <action-name> [owner <action-owner>] | | | no action | | +---count <number> | | | no count | | +---day-of-month {<day-number> [..<day-number>]|all} | | | no day-of-month | | +---description <description-string> | | | no description | | +---end-time [<date>|<day-name>] <time> | | | no end-time | | +---hour {<hour-number> [..<hour-number>]|all} | | | no hour | | +---interval <seconds> | | | no interval | | +---minute {<minute-number> [..<minute-number>]|all} | | | no minute | | +---month {<month-number> [..<month-number>]|<month -name> [..<month-nam>]|all} | | | no month | | +---no shutdown | | | shutdown | | +---type <schedule-type> | | +---weekday {<weekday-number> [..<weekday -number>]|<day-name> [..<day-nme>]|all} |... |
2.4. The CLI command prompt
By default, the CLI command prompt indicates the device being accessed and the current CLI context. For example, the prompt: A:ALA-1>config>router>if# indicates the active context, the user is on the device with hostname ALA-1 in the configure>router>interface context. In the prompt, the separator used between contexts is the “>” symbol.
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. New contexts are newly created for logical entities when the user first navigates into the context.
Since, 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.
All special characters (#, $, etc.) must be enclosed within double quotes, otherwise it is seen as a comment character and all characters on the command line following the # are ignored. For example:
When changes are made to the configuration file a “*” appears in the prompt string (*A:ALU-7210) indicating that the changes have not been saved. When an admin save command is executed the “*” disappears. This behavior is controlled in the saved-ind-prompt command in the environment context.
2.5. Displaying configuration contexts
The info and info detail commands display configuration for the current level. The info command displays non-default configurations. The info detail command displays the entire configuration for the current level, including defaults. The following example shows the output that displays using the info command and the output that displays using the info detail command.
2.6. EXEC files
The exec command allows the user 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 by a user 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.
2.7. Entering CLI commands
This section provides information about entering CLI commands and parameters.
2.7.1. 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 the <Tab> key or space bar is pressed. When typing a command, the <Tab> key or space bar invokes auto-completion. If the keystrokes entered are definite, auto-completion will complete the command. If the letters are not sufficient to identify a specific command, pressing the <Tab> key or space bar will display commands matching the letters entered. System commands are available in all CLI context levels.
2.7.2. Unordered parameters
In a context, the CLI accepts command parameters in any order as long as the command is formatted in the correct command keyword and parameter syntax. Command completion will still work as long as enough recognizable characters of the command are entered.
The following output shows different static-route command syntax and an example of the command usage.
2.7.3. Editing keystrokes
When entering a command, special keystrokes allow for editing of the command. The following table describes the command editing keystrokes.
Table 11: Command editing keystrokes
Editing action | Keystrokes |
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 | <Esc><b> |
Move forward one word | <Esc><f> |
Convert rest of word to uppercase | <Esc><c> |
Convert rest of word to lowercase | <Esc><l> |
Delete remainder of word | <Esc><d> |
Delete word up to cursor | <Ctrl-w> |
Transpose current and previous character | <Ctrl-t> |
Enter command and return to root prompt | <Ctrl-z> |
Refresh input line | <Ctrl-l> |
2.7.4. 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 forward slash “/” or backward slash “\” cannot be used with the environment alias command.The commands are interpreted as absolute path. Spaces between the slash and the first command will return an error. Commands that are already global (such as ping, telnet, exit, back, etc.) cannot be executed with a forward slash “/” or backward slash “\” at the beginning of the command line.
The command may or may not change the current context depending on whether or not it is a leaf command. This is the same behavior the CLI performs when CLI commands are entered individually, for example:
or
Note that an absolute path command behaves the same as manually entering a series of command line instructions and parameters.
For example, beginning in an IES context service ID 4 (IES 4),
behaves the same as the following series of commands.
If the command takes you to a different context, the following occurs:
becomes
Example: config>service>ies>exit all configure service vpls 5 create config>service>vpls>
2.7.5. History
The CLI maintains a history of the most recently entered commands. The history command displays the most recently entered CLI commands.
2.7.6. Entering numerical ranges
The 7210 SAS CLI allows the use of a single numerical range as an argument in the command line. A range in a CLI command is limited to positive integers and is denoted with two numbers enclosed in square brackets with two periods (“..”) between the numbers:
where x and y are positive integers and y-x is less than 1000.
For example, it is possible to shut down ports 1 through 10 in Slot 1 on MDA 1. A port is denoted with “slot/mda/port”, where slot is the slot number, mda is the MDA number and port is the port number. To shut down ports 1 through 10 on Slot 1 and MDA 1, the command is entered as follows:
<Ctrl-C> can be used to abort the execution of a range command.
Specifying a range in the CLI does have limitations. These limitations are described in the following table.
Table 12: CLI range use limitations
Limitation | Description |
Only a single range can be specified. | It is not possible to shut down ports 1 through 10 on MDA 1 and MDA 2, as the command would look like configure port 1/[1..2]/[1..10] and requires two ranges in the command, [1..2] for the MDA and [1..10] for the port number. |
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. |
The range cannot cause a change in contexts. | Commands should be formed in such a way that there is no context change upon command completion. For example, configure port 1/1/[1..10] will attempt to change ten different contexts. When a range is specified in the CLI, the commands are executed in a loop. On the first loop execution, the command changes contexts, but the new context is no longer valid for the second iteration of the range loop. A “Bad Command” error is reported and the command aborts. |
Command completion may cease to work when entering a range. | After entering a range in a CLI command, command and key completion, which occurs by pressing the <Tab> or spacebar, may cease to work. If the command line entered is correct and unambiguous, the command works correctly; otherwise, an error is returned. |
2.7.7. Pipe/match
The 7210 SAS devices support the pipe feature to search one or more files for a specific character string or pattern.
Note: When using the pipe/match command the variables and attributes must be spelled correctly. The attributes following the command and must come before the expression/pattern. The following are examples of the pipe/match command 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” > cf3cf1:\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
where:
For example:
The following table describes regular expression symbols and interpretation (similar to what is used for route policy regexp matching). Table 14 describes special characters.
Table 13: 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) |
() | Define 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 at 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. |
> | Redirect output |
Table 14: Special characters
Options | Similar to | Description |
[:upper:] | [A-Z] | uppercase letters |
[:lower:] | [a-z] | lowercase letters |
[:alpha:] | [A-Za-z] | upper- and lowercase letters |
\w | [A-Za-z_] | word characters |
[:alnum:] | [A-Za-z0-9] | digits, upper- and lowercase letters |
[:digit:] | [0-9] | digits |
\d | [0-9] | digits |
[:xdigit:] | [0-9A-Fa-f] | hexadecimal digits |
[:punct:] | [.,!?:...] | punctuation |
[:blank:] | [ \t] | space and TAB |
[:space:] | [ \t\n\r\f\v] | blank characters |
\s | [ \t\n\r\f\v] | blank characters |
2.7.8. Redirection
The SR OS supports redirection (“>”), which allows the operator to store the output of a CLI command as a local or remote file. Redirection of output can be used to automatically store results of commands in files (both local and remote).
In some cases only part of the output might be applicable. The pipe/match and redirection commands can be combined:
2.8. Configuration rollback
 | Note: This feature is only supported on 7210 SAS-R6, 7210 SAS-R12, and 7210 SAS-Mxp. |
The Configuration Rollback feature provides the ability to “undo” a configuration and return to previous router configuration states while minimizing impacts to services.
This feature gives the operator better control and visibility over 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, when experimenting or when problems are identified in the configuration during actual network operation).
The advantages of this feature are as follows:
- By not having to reboot the router, changes made to a router configuration have minimal impact on services provided by the 7210 SAS.
- There is no impact to areas of configuration that did not change, but there are some exceptions.
Configuration parameters that changed (or items that a changed configuration has dependencies on) are first removed (return to default), and the previous values are then restored (can be briefly service impacting in changed areas).
A history of changes is preserved using checkpoint IDs that allow rollback to different points, as well as examination of changes made, as shown in the following figure.
Figure 1: Rollback operation
2.8.1. Feature behavior
The following list describes detailed behavior and CLI usage of the rollback feature:
- The user can create a rollback checkpoint, and later, return to this checkpoint with minimal impacts to services by using the following command.admin>rollback# save [comment comment-string]comment-string: a 255 character comment associated with the checkpoint
- 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 configuration information. The BOF file (and BOF configuration) is not part of a rollback save or rollback. A rollback does not change any of the BOF configuration. The BOF contains basic information for the node and does not change frequently (mostly during initial commissioning of the node).
- A rollback save command can be automatically executed (scheduled, for example, monthly) using the CRON facility.
- The latest rollback checkpoint file uses a suffix of “.rb”. The next latest rollback checkpoint file has a suffix of “.rb.1”, the next oldest has a suffix of “rb.2”, etc.:file-url.rb <--- latest rollback filefile-url.rb.1…file-url.rb.9 <--- oldest rollback file
- When a rollback save [no “-”] 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 (the latest files and files 1 through 9, where checkpoint file 9 is deleted during the next rollback-save).
- The location and name of the rollback checkpoint files are configurable to be local storage (e.g. compact flash) or remote storage. The file URL must not contain a suffix (just a path/directory and filename). The suffix for rollback checkpoint files is .rb and is automatically appended to rollback checkpoint files.config>system>rollback# rollback-location file-url
- There is no default rollback location. If a location is not specified (or it is cleared using no rollback-location) and a rollback save is attempted, the rollback save will fail and return an error message.
- On the 7210 SAS-R6 and 7210 SAS-R12, the entire set of rollback checkpoint files can be copied from the active CPM CF to the inactive CPM CF. This synchronization is done through the following command:admin>redundancy# rollback-sync
- The operator can enable automatic synchronization of rollback checkpoint files between the active CPM and inactive CPM. When this automatic synchronization is enabled, a rollback save will cause the new checkpoint file to be saved to both the active and standby. The suffixes of the old checkpoint files on both active and standby CPMs are increased.
Note: The automatic synchronize only causes the one new checkpoint file to be copied to both CFs (the other 9 checkpoints are not automatically copied from active to standby, but that can be done manually using the admin>redundancy>rollback-sync command).
config>redundancy# [no] rollback-sync
- config>redundancy>synchronize {boot-env|config} and admin>redundancy>synchronize {boot-env|config}” 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 sync 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 than the one that was deleted (to close the “hole” in the list of checkpoint files and create room to create another checkpoint).
- If configure>redundancy>rollback-sync is enabled, a rollback delete will also delete the equivalent checkpoint on the standby CF and shuffle 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.
- As shown in the following figure, support for rolling back to a previous configuration (a saved rollback checkpoint) with minimal impact on services. The previous configuration will be loaded and take 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 (no deletions or renumbering). This means that if an operator issues a “rollback revert 3” and issues a “rollback-save”, the resulting rollback checkpoint files “file-url.rb” and “file-url.rb.4” will contain the same rollback state/configuration.
- The boot-good-exec or boot-bad-exec are not automatically executed after a rollback.
- Impacts to the running services are minimized during a rollback as follows:
- There is no impact in areas of configuration that did not change, except for some exceptions.
- Configuration parameters that changed (or items that a changed configuration has dependencies on) are first removed and the previous values are restored (can be briefly service impacting in changed areas). Some examples are as follows:
- If the SAP ingress policy num-qos-resources value is different in the active configuration and in comparison to the value in the rollback checkpoint, all the SAPs are deleted and created again. This is done to guarantee that configuration of all the SAPs succeeds when moving to the previous configuration.
- Changing some of the parameters in the SAP egress policy requires the port to be shut down. Therefore, when moving to a previous configuration results in change of these values, the port is shut down, the old SAP egress policy is removed, and the new SAP egress policy is applied.
- A rollback will undo any SNMP sets or direct CLI configuration commands that occurred since the last checkpoint creation.
- During the period when a node is processing a rollback revert command, both CLI commands from other users and SNMP commands will 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 one 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 exec scripts. A normal configuration file (from an admin save) cannot be renamed as a rollback checkpoint and a rollback can be executed as long as the hardware change was an addition of hardware to the node (for example, added a new IOM into a previously empty slot).
- A rollback is not guaranteed to work if hardware was removed or changed (for example, the IOM was removed or an MDA was swapped for a different MDA type).
- Rollback across a change to the following parameters is not supported:
- system resource profile commands
- PTP commands
- 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). Admin reboot does not “break the chain” for rollback.
- The Configuration Rollback feature is incompatible with the use of Time Of Day (ToD) policies and functionality. Rollback save and rollback revert operations are blocked if any ToD policies are active (for example, assigned to objects such as a SAP).
- Any configuration or state change performed under the debug branch of CLI is not saved in the rollback checkpoint file nor impacted by a rollback.
- Rollbacks to a checkpoint created in a more recent release is not supported.
- 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, etc.:
- SAA jobs that are running when a rollback revert is initiated, and need configuration changes due to the rollback, will be stopped. If the SAA job is a continuous type, it will be re-started 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 need to be manually restarted if they need to be run again.
- If max-nbr-mac-addr is reduced as part of the revert but the number of MAC addresses in the forwarding database is greater than the maximum number of MAC addresses, 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 to proceed with the rollback.
- If a force-switchover command 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 admin state), the rollback revert will automatically remove the force-switchover and the node will revert 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. The following are some examples:
- Configuration changes that require a shutdown and no shutdown to be done by an operator to take operational effect also need a manual shutdown and no shutdown to be performed by the operator to take operational effect after a rollback if the rollback changes those configuration items. Some examples include:
- Changes to autonomous system or confederation values require a BGP shutdown and no shutdown.
- Changes to VPRN max-routes require a shutdown and no shutdown on the VPRN service.
- Changes to an OSPF or ISIS export limit require a shutdown and no shutdown on OSPF or ISIS.
- Configuration changes to an MSAP policy that requires a tools>perform>subscriber-mgmt>eval-msap command to take operational effect on subscribers that are already active. Rollback will change the MSAP policy configuration, but if it is required to have the configuration changes applied to the active subscribers, the operator will have to run the eval-msap tools command.
- Changes to the SAP egress policy require a port shutdown and no shutdown. This is done automatically by the software when it detects a change.
- Changes to the number of QoS resources in the SAP ingress policy results in deletion and creation of all the SAPs. This is done to ensure that the configuration can be successfully recreated using the SDX file.
- Any uncommitted changes (that is, the begin command was entered and some changes were made, but the commit command was never entered) in the following areas will be lost/cleared when a rollback revert is initiated:
- config>router>policy-options
- config>system>sync-if-timing
- Some card and MDA commands require a reboot, remove, or rebuild of an entire card or XMA/MDA. When these commands need to be executed as part of a rollback, the impacted cards/MDAs will be listed in a warning and the operator will be prompted with a single y/n prompt to decide whether to proceed or not. This prompting will not occur for a rollback initiated via SNMP, nor 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 the following:
- config>card>card-type
- config>card>mda
- config>card>mda>mda-type
- Although the use of the control-C key combination is not recommended during a rollback revert, it is supported through CLI and SNMP. Interrupting a rollback revert may leave the router in a state that is not necessarily something between the old active configuration and the rollback checkpoint since 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.
- A high availability CPM switchover during a rollback revert will cause the rollback operation to abort. The newly active CPM will have 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.
2.8.2. Rescue configuration
A special rescue configuration checkpoint can be created that an operator can rollback revert to at any time. The rescue configuration has its own keyword (rescue) and does not use the same rolling suffix indexes 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 (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 correct management access to the node.
The location and filename of the rescue file are configurable. The 7210 SAS appends an .rc suffix to the specified rescue filename.
2.8.3. Operational guidelines
The following points provide some operational guidance on the usage of rollback:
- Both admin save and rollback save should be done periodically:
- Do an admin save to back up a complete configuration file that can be used during router reboot:
- Used with a reboot as a last resort.
- Do an admin save after any major hardware changes or major service changes.
- Should be done after any software upgrade.
- Do a rollback save to create a rollback checkpoint:
- used for intermediate checkpoints that can be recovered with minimal impacts to services
- should be done each time that a moderate amount of configuration changes have been made
- should be done after any hardware changes
- should be done after any software upgrade
- can also be scheduled with CRON (for example, once every 1 or 2 weeks)
- A new rescue save must be created when hardware is changed.
- Rollback checkpoint files are not editable nor compatible/interchangeable with configuration files (generated with admin save).
- Avoid repeatedly executing rollback save without also occasionally executing admin save. If you really get into a bad situation, you may have to use one of your admin save configurations as the primary configuration for an admin reboot.
- After a software upgrade has occurred and the system is operating as expected, it is recommended to create a rollback checkpoint file using the admin>rollback>save command and to save the configuration using admin>save. This ensures that a good checkpoint fully compatible with the new release is available shortly after the upgrade.
- A set of rollback checkpoints can be created to support busy/quiet days or weekend/weekdays and CRON can be used to shift between them.
- It is recommended to create a rollback checkpoint before a rollback revert is initiated (especially if there have been significant configuration changes since the last checkpoint was created). If the rollback is especially significant (a lot of major changes) it is also a good practice to do an admin save just 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 fails during execution, it should be attempted again. The second attempt will typically complete the remaining configuration changes required to fully revert to the desired checkpoint.
- On the 7210 SAS-R6 and 7210 SAS-R12, when a new backup CPM is commissioned, the user should issue the admin>redundancy>rollback-sync to copy the entire set of rollback files from the active CPM checkpoint file (CF) to the new standby CPM CF. If the operator needs the system to automatically copy new rollback checkpoints to both CFs whenever a new checkpoint is created, the config>redundancy>rollback-sync should be configured.
- On the 7210 SAS-R6 and 7210 SAS-R12, a high availability CPM switchover during a rollback revert will cause the rollback operation to abort. The newly active CPM will have an indeterminate configuration. A log event is created and the operator is advised to repeat the rollback revert operation to the same checkpoint.
- A rollback checkpoint file stores the rollback location and the local and remote maximum checkpoint values, and as such a rollback revert operation can change those values. If an operator changes the local and remote maximum checkpoint values, it is recommended to delete all the existing checkpoints otherwise a subsequent rollback revert could change the max values back to a previous value.
- If a warning prompt (y/n) is displayed when a rollback revert is initiated, it is highly suggested to respond ‘no’ to the warning prompt the first time, save a rollback checkpoint before attempting this rollback revert, and execute the rollback>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.
2.8.4. Configuration guidelines and restrictions
The following are the limitations of the configuration rollback feature for the 7210 SAS-R6, 7210 SAS-R12, and 7210 SAS-Mxp:
- Resource profile policy changes cannot be rolled back. That is, if there is a change in resource policy/parameters between active configuration and checkpoint, rollback will not proceed.
- PTP is not supported.
- For SAP ingress QoS, due to the slice information available in the .sdx file, whenever there is a change in ingress QoS policy attached to a SAP, or if there are any additional SAPs in the checkpoint file, all SAPs are torn down and rebuilt. The user will be prompted before this occurs.
- A SAP that has a change in egress QoS policy will be shut down and will do a no shutdown after a delay.
- During rollback, all ports and SAPs are shut down and brought back up again. This brings down traffic and control protocols that have been initiated or are transitioning through the node during rollback.
- Rollback is not permitted when there is a change to port-scheduler-mode.
- Back-to-back rollbacks, particularly scaled ones, are not recommended. Users must allow sufficient time for the system to process the current rollback before initiating a new one.
- On the 7210 SAS-R6 and 7210 SAS-R12, if there are additional differences in resource profile templates between two rollback points, the rollback procedure does not roll back any changes. An error message is displayed asking the user to undo these resource profile template changes manually.
- Rollback is not allowed between two rollback points if there are changes in the slice allocation in the same resource profile template. On the 7210 SAS-R6 and 7210 SAS-R12, the restriction also applies for a template that is not associated with any card.
- On the 7210 SAS-R6 and 7210 SAS-R12, if the resource profile templates are the same across two different rollback points but the attachment to the card is different, it may result in resource allocation failures in scaling scenarios.