3.2.1. CLI Contexts

The CLI is used to access, configure, and manage 7705 SAR routers. CLI commands are entered at the command line prompt. Access to specific CLI commands is controlled by the permissions set by the system administrator. Entering a CLI command makes navigation possible from one command context (or level) to another. When the user enters a CLI session, they are in the root context. To navigate to other levels, the user enters the name of successively lower contexts. For example, entering the configure or config command at the root level takes the user to the config context. The active CSM slot displays in the command prompt at the beginning of the CLI context as shown below:

In any CLI context, commands can be entered at that context level by entering the text. Pressing <Enter> moves to a lower context. The user can also include commands from lower contexts at one context level as long as the command and parameter syntax is correct.

The following example shows two methods of navigating to a service SDP ingress level:

Method 1: Enter all commands on a single line.

Method 2: Enter each command on a separate line.

The CLI returns an error message if the syntax is incorrect.

3.2.2. CLI Syntax

Table 2 lists command syntax symbols. Differences between the syntax used in the CLI and in the Command Reference sections of the 7705 SAR guides is noted in the table.

3.2.3. CLI Root-Level Commands

The commands listed in Table 3 are available at the root level of the CLI hierarchy. For the command descriptions, refer to the Command Reference sections of the applicable guides.

3.2.4. CLI Global Commands

The commands listed in Table 4 are implemented as global commands that can be entered at any level in the CLI hierarchy. The exception is the info command, which can only be entered in a configuration context. To display a list of all system global commands, enter help globals in the CLI.

3.2.5. CLI Environment Commands

The CLI environment commands listed in Table 5 are found in the root>environment context of the CLI tree. These commands control session preferences for a single CLI session.

3.2.6. CLI Monitor Commands

The CLI monitor commands are found in the root>monitor context of the CLI tree. Monitor commands display specified statistical information related to the monitor subject (such as filter, port, router, and service) at a configurable interval until a count is reached.

The monitor command output displays a snapshot of the current statistics. The output refreshes with subsequent statistical information at each configured interval and is displayed as a delta to the previous output.

The <Ctrl-c> keystroke interrupts a monitoring process. Monitor command configurations cannot be saved. The commands must be entered for each monitoring session. If the maximum limits are configured, the statistical information can be monitored for a maximum of 60 × 999 s (approximately 1000 minutes, or 16.6 hours).

The CLI monitor commands are listed in Table 6.

3.8.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 spacebar is pressed. When typing a command, the <Tab> key or spacebar invokes auto-completion. If the keystrokes entered are sufficient to identify a specific command, auto-completion completes the command. If the letters are not sufficient to identify a specific command, pressing the <Tab> key or spacebar displays commands matching the letters entered.

The command completion functionality works for both keywords and for optional parameters that have already been configured. When using command completion for optional parameters, the <Tab> key must be used.

For example, entering “i <Tab> returns the following user-configured interface names:

System commands are available at all CLI context levels.

3.8.2. Unordered Parameters

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

3.8.3. Editing Keystrokes

When entering a command, special keystrokes allow for editing of the command. Table 8 lists the command editing keystrokes.

3.8.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 commands are interpreted as absolute paths. Spaces between the slash and the first command will return an error.

The command may or may not 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:

or

3.8.5. History

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

3.8.6. Entering Numerical Ranges or Lists

The 7705 SAR CLI allows the use of a single numerical range, a list of values (elements), or a combination of both 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 [x.. y], where x and y are positive integers and y-x is less than 1000. For example, to configure a range of VPLS service IDs from 20 to 30 for a customer, enter:

config service vpls [20..30] customer 1 create no shutdown

A list of values contains discrete integer elements, in any order. For example, to configure a list of VPLS service IDs that are not sequential, enter:

config service vpls [3,5,7] customer 1 create no shutdown

To configure a list of interface names (interface names must begin with a letter), put the alphabetic part of the name outside of the brackets; for example:

config router interface intf[1,4,6] no shutdown

This command creates interfaces with names intf1, intf4, and intf6.

Lists can contain ranges as elements, as well as values. For example, to configure multiple ports on MDA 1, enter:

config port 1/1[1..6,8,10, 21..32] no shutdown

CLI commands can also contain ranges or lists of hexadecimal values; for example, [0x0f..0x13], [0x4,0x8,0xc]. This allows ranges to be used when working with data that is normally expressed in hexadecimal, such as IPv6 addresses or MAC addresses.

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, with 0 referring to the first range in the command, 1 to the second, and so on up to the maximum of six ranges. For example:

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

gives vprn 11 the router ID 10.20.11.1, vprn 12 the router ID 10.20.12.1, and so on.

<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 summarized in Table 9.

3.8.7. Pipe/Match

The 7705 SAR supports the pipe/match (...| match) feature to search one or more files for a specified character string or pattern.

Match syntax:

where:

pattern: a string or regular expression (maximum 200 characters)

context: displays the context associated with the matching line

parents: displays the parent context information

children: displays the child context information

all: displays both parent and child context information

ignore-case: ignores the case in the string (uppercase or lowercase)

max-count lines-count: displays the matching lines, up to the specified number (1 to 2147483647)

expression: the pattern is interpreted as a regular expression

invert-match: displays all the lines that do not contain the string specified in pattern

pre-lines pre-lines: displays the lines prior to the matching line, up to the specified number (0 to 100)

post-lines lines-count: displays the lines after the matching line, up to the specified number (1 to 2147483647)

For example:

Table 10 describes regular expression symbols and interpretation (similar to what is used for route policy regexp matching).

Table 11 identifies the special character options.

3.8.8. Pipe/Count

The 7705 SAR supports a pipe/count command (...| count) that provides a count of the number of lines that would have otherwise been displayed. The pipe/count command is particularly useful when used in conjunction with the pipe/match command in order to count the number of output lines that match a specified pattern.

For example:

3.8.9. Redirection

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

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

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

3.9.1. Rollback Checkpoint and Rescue Files

Rollback checkpoint files and rescue files are created with the rollback save command. A rollback checkpoint file can be saved at any time or configured to be automatically saved on a recurring schedule using the 7705 SAR CRON feature. For more information, see CRON.

Rollback checkpoint and rescue files contain all current operationally active configurations, including configuration changes from CLI commands in the config context and SNMP sets. Rollback checkpoint files are intended to be saved whenever there have been a moderate number of changes to the configuration, in order to create a series of intermediate checkpoints that operators can return to. The rollback rescue file is intended to be a permanent stable configuration that can be reverted to if needed.

Rollback checkpoint and rescue files do not contain any BOF configuration information or any configuration or state changes performed under the debug branch of the CLI. Similarly, performing a CLI configuration rollback never impacts the BOF configuration or any command from the debug CLI branch.

When a rollback save command is executed, a rollback checkpoint or rescue file is saved in the configured location. The latest rollback checkpoint file is saved with the suffix *.rb. The suffixes of all previously saved rollback checkpoint files are automatically incremented by one (*.rb becomes *.rb.1, *.rb.1 becomes *.rb.2, and so on). The rescue file is saved with the suffix *.rc.

By default, there can be 10 rollback checkpoint files, the latest with suffix *.rb and nine older files with suffixes *.rb.1 through *.rb.9. If the maximum number of checkpoint files is reached and a new one is saved, the oldest checkpoint file is deleted. The maximum number of rollback checkpoint files that can be saved can be configured with the local-max-checkpoints and remote-max-checkpoints commands.

There can only be one rollback rescue file. When a new rescue file is saved, the existing file is deleted. The rescue file is not impacted by the number of rollback checkpoint files — there will always be one rescue file available.

Operators can view a list of rollback checkpoint or rescue files with the rollback view command. The following information is displayed for the files:

A rollback compare command is also available that allows operators to compare different checkpoint files to each other or to the current operating configuration. The command output highlights any differences between the configurations.

Rollback checkpoint and rescue files are not editable or interchangeable with configuration files, such as those generated with an admin save command.

Both admin save and rollback save should be performed periodically. The admin save command backs up the complete configuration file to be used during a router reboot and should be performed after any major service changes or hardware and software upgrades. The rollback save command should be performed to create intermediate checkpoints whenever a moderate number of changes have been made to the configuration.

Rollback checkpoint files and rescue files can be deleted with the dedicated admin>rollback>delete command. When a checkpoint file is deleted, the suffix ID numbers of all older files are automatically decremented.

If a rollback checkpoint file is manually deleted, using, for example, the file delete command, the suffix ID numbers of older checkpoint files are not decremented, nor is the backup checkpoint file deleted from the standby CSM. This creates a gap in the checkpoint file list. New rollback checkpoint files can still be created, but the gap is not filled until enough files have been created to roll the gap off the end of the list.

3.9.2. Performing a CLI Configuration Reversion

The rollback revert command is used to return the CLI configuration, including all configuration commands and SNMP sets, to the saved configuration in a rollback checkpoint or rescue file. CLI configuration reversion can be used to quickly correct problems in the configuration during network operation or to aid in experimentation by enabling a return to known settings after trying a new configuration.

The CLI configuration reversion is performed without a reboot and with minimal impact on the services being provided by the 7705 SAR. Configuration parameters that have changed since the checkpoint file was created, or items on which changed configurations have dependencies, are first reset to their default values and then restored to their previous values from the rollback checkpoint file. Performing a configuration reversion can be briefly service-impacting in changed areas. There are no service impacts to configuration areas that did not change since the rollback checkpoint file was created.

If a rollback reversion process includes any commands that will remove, rebuild, or reboot an adapter card or fixed platform, the impacted adapter cards and platforms are listed in a warning and the operator is asked whether to proceed or not with a y/n prompt. There is no prompt if the rollback reversion is initiated via SNMP or if the now keyword is used. The following are examples of adapter card and fixed platform commands that may generate a warning:

While the 7705 SAR is processing a rollback revert command, CLI and SNMP commands from other users are still accepted and applied to the system. The only commands that are blocked during this process are other rollback commands including revert, save, and compare. Only one rollback command can be processed at a time.

Performing a rollback reversion does not have any effect on existing rollback checkpoint and rescue files; files are not renumbered or deleted. For example, if an operator reverts to rollback checkpoint file 3, the file remains as *.rb.3. If the operator then executes a rollback save command, the current configuration is saved as the latest rollback (extension *.rb) and *.rb.3 is incremented to *.rb.4. In this scenario, both the latest rollback checkpoint file and checkpoint file 3 will have the same configuration information.

Currently running or scheduled CRON jobs are handled like all other configurations during a rollback reversion. The CRON configuration will revert to the configuration at the time the checkpoint was created.

The boot-good-exec or boot-bad-exec commands must be manually executed after a rollback reversion; they are not automatically run.

3.9.2.1. Rollback Restrictions

Some hardware or software changes can prevent operators from performing the rollback or can affect the operation of the node following the reversion.

If hardware is removed or changed after a rollback checkpoint file is saved, the node may not function as expected after the system reverts to that configuration. There is no effect if new hardware is added into previously empty slots.

A CLI rollback reversion is not supported if the rollback checkpoint file was saved in a previous major software load or if it was saved in a more recent major or minor software load. For example:

1. a node running Release 20.4.R1 cannot revert to a checkpoint file saved in Release 9.0.R4
2. a node running Release 9.0.R4 cannot revert to a checkpoint file saved in Release 20.4.R1
3. a node running Release 9.0.R4 cannot revert to a checkpoint file saved in Release 9.0.R6

CLI rollback reversion is supported if the checkpoint file was saved in a previous minor software release. For example, a node running Release 9.0.R6 can revert to a checkpoint file saved in Release 9.0.R4. It is also supported after an operator performs an admin reboot or changes the primary configuration and then performs an admin reboot. The reboot does not remove any previously saved rollback files.

If the system runs out of memory during a CLI rollback reversion, the process aborts and the node remains in an indeterminate configuration state. The CLI screen displays a warning message that the CLI reversion failed.

A CLI rollback reversion may also fail in rare cases if the node requires a long time to complete the configuration changes. If the CLI rollback reversion fails during execution, it should be attempted again. The second attempt typically completes the remaining configuration changes.

A high availability CSM switchover during a rollback reversion will cause the rollback process to abort, and the newly active CSM will have an indeterminate configuration. This may not be immediately obvious if the CLI rollback reversion was nearly complete when it was interrupted. To assist operators, a log event is created and the results of the last rollback reversion can be displayed with the show system rollback command. If a high availability switchover occurs during a rollback (or within a few seconds of a rollback completing), the Last Revert Result field will display Interrupted and the operator is advised to repeat the rollback revert operation to the same checkpoint.

Caution: Although the use of the <Ctrl-c> key combination is not recommended during a rollback revert, it is supported in the CLI and SNMP. Interrupting a rollback revert command may leave the router in an indeterminate state between the active and saved configuration. If <Ctrl-c> is used during a CLI rollback reversion, the 7705 SAR displays a warning message to indicate that the operator must examine the configuration and potentially issue another rollback revert command to return to a known, complete configuration.

3.10.1. Basic Operation

In order to edit the candidate configuration, the user must first enter candidate edit mode with the candidate>edit command. The user can enter and quit candidate edit mode as many times as they wish before committing the candidate configuration.

In candidate edit mode, the user 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, there is also a single global candidate configuration instance. All users make changes in the same global candidate configuration and any command that affects the candidate configuration (such as a save or commit) applies to the changes made by all users.

Users can enter an exclusive candidate edit mode by blocking other users, or sessions of the same user, from entering candidate edit mode.

When a candidate configuration is committed, the user can request an additional confirmation of the configuration. If the confirmation is not given with the confirm command within the specified time frame, the router automatically reverts to a configuration state before the candidate configuration changes were applied. If this automatic reversion occurs, the candidate configuration is not cleared and users can continue to edit it and try the commit later.

If the commit operation is successful and the confirm command is issued (if requested during the commit), all the candidate changes take operational effect and the candidate configuration is cleared. If there is an error processing the commit, the router returns to a configuration state before the candidate changes were applied. The candidate configuration is not cleared and users can continue to edit it and try the commit later.

A candidate commit may fail for various reasons, including:

If a commit fails, the system generates error messages to help the user correct the candidate configuration.

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 commands (such as copy, insert, and replace) are available to correct and reorder an existing candidate configuration.

Candidate edit mode is primarily intended for building a candidate configuration using commands from the configure branch of the CLI. Although many CLI commands in other branches are supported, access to some CLI commands and branches are blocked, including:

The candidate configuration can be saved to a file and loaded into a new candidate configuration later. A saved candidate file is similar to, but not exactly the same as, a 7705 SAR configuration file generated with an admin save command. The saved candidate file cannot be used as a configuration file and may not execute without failures.

There is no SNMP access to the candidate configuration and no SNMP management of candidates. However, when a candidate configuration is committed, any changes to the active or operational configuration are reported via the standard 7705 SAR SNMP change traps. Basic candidate status information is also available via SNMP.

The active or operational configuration can still be modified with standard CLI or SNMP commands that take immediate effect while a candidate configuration is being created or edited or a candidate commit is being processed. While in candidate edit mode, users can view the current state of the operational configuration with the info operational command.

3.10.2. Transactions and Rollback

Transactional configuration relies on the rollback mechanism to operate. By default, the 7705 SAR automatically creates a new rollback checkpoint after a successful candidate 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 creation of an automatic rollback checkpoint after a successful commit. If the commit fails, no rollback checkpoint is created. If the confirmed option is used during the candidate commit, a rollback checkpoint is created and exists whether or not the confirm command is issued.

Any configurations that are not supported in a rollback revert are also not supported in candidate edit mode. See CLI Configuration Rollback for more information.

3.10.3. Authorization

Authorization works transparently in candidate edit 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 a user has permission to access the configure filter context, they automatically have access to the same context when in candidate edit mode.

The candidate load and save commands load and save only those items that the user is authorized to access.

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

The candidate editing commands (such as adding or removing lines) only allow the user to modify items that they are authorized to access.

The candidate commit and discard commands, along with the admin>rollback> revert command, impact all items in the candidate configuration and are not affected by authorization.