2. CLI interface
The CLI is an interface for configuring, monitoring, and maintaining the SR Linux. This chapter describes basic features of the CLI and how to use them.
2.1. Accessing and using the CLI
2.1.1. Accessing the CLI
After the SR Linux device is initialized, you can access the CLI using a console or SSH connection. See the SR Linux hardware documentation for information about establishing a console connection and enabling and connecting to an SSH server.
Use the following command to connect to the SR Linux and open the CLI using SSH:
ssh admin@<IP Address>
Example:
2.1.2. Using the CLI help functions
The CLI help functions (? and help) can assist in understanding command usage and indicate which configuration mode you are in.
Enter a question mark (?) after a command to display the command usage. For example, entering a question mark after the command network-instance, shows its usage.
Example 1:
Example 2:
Enter help at the top level to show the current configuration mode and details on other configuration modes. For more information about configurations, see Configuration modes.
2.1.3. Using the CLI auto-complete function
To reduce keystrokes or aid in remembering a command name, use the CLI auto-complete function.
Enter a tab at any mode or level to auto-complete the next command level. If multiple options are available, a popup will appear.
- When a command is partially entered, the remainder of the command appears ahead of the prompt in lighter text. Press the Tab key to complete the command.
- When the Tab key is pressed and there are multiple options, the options are shown:
2.1.4. Using the CLI
Use shortcuts to move the cursor on the command line, complete commands, and recall commands previously entered. Shortcuts can also make syntax correction easier. Table 3 lists common shortcuts.
Table 3: CLI keyboard shortcuts
Task | Keystroke |
Move cursor to the beginning of the line | Ctrl+A |
Move cursor to the end of the line | Ctrl+E |
Move cursor one character to the right | Ctrl+F or Right arrow key |
Move cursor one character to the left | Ctrl+B or Left arrow key |
Move cursor forward one word | Esc F |
Move cursor back one word | Esc B |
Transpose the character to the left of the cursor with the character the cursor is placed on | Ctrl+T |
Complete a partial command | Enter the first few letters, then press the Tab key |
Recall previous entry in the buffer | Page up key |
Navigate one level up within a context. For example: --{running}--[interface ethernet-1/1 subinterface 1]-- # exit --{running}--[interface ethernet-1/1]-- | Type: exit |
Return to the root context. For example: --{running}--[interface ethernet-1/1 subinterface 1]-- # exit all --{running}--[ ]-- | Type: exit all |
2.1.5. Closing the CLI
Close the CLI using one of the following methods:
- Press Ctrl+D.
- Enter the quit command at the CLI prompt.
2.2. Configuration modes
Configuration modes define how the system is running when transactions are performed. Supported modes are the following:
- Candidate – Use this mode to modify a configuration. Modifications are not applied to the running system until a commit command is issued. When committed, the changes are copied to the running configuration and become active.There are different types of configuration candidates. See Configuration candidates.
- Running – Use this mode to display the currently running or active configuration. Configurations cannot be edited in this mode.
- State – Use this mode to display the configuration and operational states. The state mode displays more detailed information than show mode.
- Show – Use this mode to display configured features and operational states. The show mode displays less information than state mode.
2.2.1. Configuration candidates
You can modify the candidate configuration in different modes:
- Exclusive
- Shared
- Private
- Name
2.2.1.1. Exclusive mode
When entering candidate mode, if you specify the exclusive keyword, it locks out other users from making changes to the candidate configuration.
You can enter candidate exclusive mode only under the following conditions:
- The current shared candidate configuration has not been modified.
- There are no other users in candidate shared mode.
- No other users have entered candidate exclusive mode.
2.2.1.2. Shared mode
By default, the candidate configuration is in shared mode. This allows multiple users to modify the candidate configuration concurrently. When the configuration is committed, the changes from all of the users are applied.
A default candidate is defined per user (see Name mode).
Use caution when allowing multiple users access to the candidate configuration at the same time. If one user commits the configuration, that commits the changes made by any other users who have modified the current candidate configuration.
2.2.1.3. Private mode
A private candidate allows multiple users to modify a configuration; however when a user commits their changes, only the changes from that user are committed. When a private candidate is created, private datastores are created and a snapshot is taken from the running database to create a baseline.
When starting a private candidate, a default candidate is defined per user with the name ‘private-<username>’ unless a unique name is defined (see Name mode).
2.2.1.4. Name mode
Candidate types support an optional name. This allows multiple users to share environments.
When a candidate is created with a name specified, a new entry is created in the /system/configuration/candidate[] list. Other users can enter the same candidate (if the candidate type is shared) using this name.
if no name is specified, then the name ‘default’ is used. This means the global shared candidate can be accessed by entering enter candidate name default or just enter candidate, For private candidates the name ‘default’ is not used (since private candidates share a list with shared candidates). Instead, private candidates are created with the name "private-<username>".
Named candidates are automatically deleted when there are no active sessions present and they are empty, or after 7 days of no session activity. This 7-day default is configurable in the /system/configuration/idle-timeout field.
2.2.2. Setting the configuration mode
After logging in to the CLI, you are initially placed in running mode. Table 4 describes the commands to change between modes.
Table 4: Commands to change configuration mode
To enter this mode: | Type this command: |
Candidate shared | enter candidate |
Candidate mode for named shared candidate | enter candidate name <name> |
Candidate private | enter candidate private |
Candidate mode for named private candidate | enter candidate private name <name> |
Candidate exclusive | enter candidate exclusive |
Exclusive mode for named candidate | enter candidate exclusive name <name> |
Running | enter running |
State | enter state |
Show | enter show |
Example 1:
To change from running to a shared candidate mode (using the default)’:
The asterisk (*) next to the mode name indicates that the candidate configuration has changes that have not yet been committed.
Example 2:
To switch between candidate shared and candidate exclusive modes, you must first switch to a different configuration mode (for example, running mode) before entering candidate shared or exclusive mode. For example:
Example 3:
To enter candidate mode for a named configuration candidate, you specify the name of the configuration candidate. For example:
2.2.3. Managing configuration conflicts
When a user enters candidate mode, the system creates two copies of the running datastore: one is modifiable by the user, and the other serves as a baseline. The modifiable datastore and the baseline datastore are collectively known as a configuration candidate.
The baseline command can assist in managing conflicts and uses the following arguments:
- baseline update - Performs an update of the complete baseline datastore. pulling in any changes that occurred in the running datastore since the baseline snapshot was taken.
- baseline diff - Shows baseline configuration changes with options to refine by area.
- baseline check - Performs a dry-run baseline check, and if conflicts are detected, an informational or warning message is generated.
2.2.4. Committing a configuration in candidate mode
Changes made during a configuration modification session do not take effect until a commit command is issued. Use the commit command in candidate mode only.
- Enter candidate mode:# enter candidate
- Enter configuration commands.
- Enter the commit command when with the required option (see Table 5).
Table 5: commit command options
Option
Action
Permitted additional arguments
commit now
Apply the changes, exit candidate mode, and enter running mode.
NA
commit stay
Apply the changes and then remain in candidate mode.
commit stay [save] [comment] [confirmed]
commit save
Apply the changes and automatically save the commit to the startup configuration. Can be used other arguments except now (e.g., commit stay save).
commit [stay] [checkpoint] save [confirmed] [comment]
commit checkpoint
Apply the changes and cause an automatic checkpoint after the commit succeeds.
commit [stay] [now] checkpoint [save] [confirmed]
commit validate
Verify that a propose configuration change passes a management server validation.
NA
commit comment <comment>
Use with other keywords (except validate) to add a user comment (e.g. commit stay comment <comment> where <comment> is a quoted string, 1-255 characters.
commit [stay] [save] [checkpoint] [confirmed] comment
commit confirmed
commit confirmed [timeout]
commit confirmed [accept | reject]
Apply the changes, but requires an explicit confirmation to become permanent. If the explicit confirmation is not issued within a specified time period, all changes are automatically reverted.
The timeout period default is 600 seconds (10 mins.), or can be provisioned with a value of 1-86400 sec.). The timeout parameter cannot be used with the accept or reject parameter.
Prior to the timer expiring, the accept parameter explicitly confirms and applies the changes. With no timer running, the reject parameter explicitly rejects the changes.
commit [checkpoint] [save] [stay] [comment] confirmed
Example 1:
This example shows the commit stay option:
Example 2:
This example shows the commit confirmed option with a custom timeout followed by an accept action.
2.2.5. Deleting configurations
Use the delete command to delete configurations while in candidate mode.
Example:
The following example displays the system banner configuration, deletes the configured banner, then displays the resulting system banner configuration:
2.2.6. Annotating the configuration
To aid in reading a configuration, you can add comments or descriptive annotations. The annotations are indicated by !!! in displayed output.
You can enter a comment either directly from the command line or by navigating to a CLI context and entering the comment in annotate mode.
Example 1:
The following example adds a comment to an ACL configuration. If there is already a comment in the configuration, the new comment is appended to the existing comment.
To replace the existing comment, use !!! instead of !! in the command.
Example 2:
The following example adds the same comment to the ACL by navigating to the context for the ACL and entering the comment in annotate mode:
You can enter multiple lines in annotate mode. To exit annotate mode, press Esc, then the Enter key.
In CLI output, the comment is displayed in the context it was entered. For example:
To remove a comment, enter annotate mode for the context and press Esc then Enter without entering any text.
2.2.7. Discarding a configuration in candidate mode
You can discard previously applied configurations with the discard command. Use the discard command in candidate mode only.
- To discard the changes and remain in candidate mode with a new candidate session, enter discard stay.
- To discard the changes, exit candidate mode, and enter running mode, enter discard now.
Example:
2.3. Using administrative commands
The common administrative CLI commands in this section can help you understand a current configuration and perform routine configuration tasks.
2.3.1. Pinging a destination IP address
Use the ping (IPv4) or ping6 (IPv6) command to contact an IP address. Use this command in any mode.
Example:
2.3.2. Tracing the path to a destination
To display the path a packet takes to a destination, use the traceroute (IPv4) or traceroute6 (IPv6) command.
Example:
To trace the route using TCP SYN packets rather than UDP or ICMP echo packets, use the tcptraceroute command.
2.3.3. Configuring the network-instance environment variable
When you enter administrative commands such as ping and traceroute, you can specify the network-instance to be used with the command. If you do not specify a network-instance, then the network-instance configured in the network-instance environment variable is used.
If you do not specify a network-instance, or the network-instance cannot be inferred from the CLI context, then the “<base>” network instance is used when no network-instance is specified in a ping or traceroute command; for example:
To configure the network-instance environment variable, use the environment network-instance command; for example:
In this example, the network-instance environment variable is set to “red”, so network instance red is implied when the ping or traceroute command is entered without a network-instance name; for example:
2.3.4. Using bash mode
From within the CLI, use the bash command to enter the bash shell. Use this command in any mode. To exit the bash shell and return to the CLI, enter exit.
Example:
You can use the bash command to enter Linux commands directly from the SR Linux CLI prompt. For example:
2.3.5. Setting commands to execute periodically
To set a command to execute periodically, use the watch command. The watch command can be used with any valid command with the exception of interactive commands (for example, ping, monitor, packet-trace, bash, and bash oneliners such as bash cat /etc/hosts). An error message is generated if an interactive command is used. Output redirection is supported.
When used, the first page of output displays. The command then re-executes every 2 seconds by default.
The watch command uses the following format:
watch <arguments> <command to watch>
All arguments must precede the command being watched. Arguments for the watch command are:
Arguments | Definition |
interval | Sets an interval for the command to re-execute. Range: 1 - 3600 seconds. Default: 2 seconds |
differences | For output that is actively changing, highlights the differences between the previous and current execution |
cumulative-differences | For output that is actively changing, highlights the differences between the first execution and the current execution |
no-colors | When used with differences or cumulative-differences, markers are used to show differences (verses colors) |
no-limit | Allows the full output of each execution to display (verses limiting to the height of the terminal) |
no-paging | Provides continuous output (verses redrawing the terminal with each execution) |
no-title | Turns off the header that shows the interval, command, number of executions that have occurred, and the time |
The command being watched does not require double quotes. In addition, the auto complete function can be used to complete a valid command.
To exit the watch command, enter Ctrl-C.
Example 1:
In the following example, the watch command is used to show interface statistics (showing in-octets and out-octets in table format). The interval is modified to 10 seconds.
Example 2:
In the following example, the watch command is used to show differences in interface statistics (with in-octets and out-octets in table format). In addition, the no-color argument is used to show the differences between previous and current execution with markers verses color indicators.
2.3.6. Using the diff command
Use the diff command to get a comparison of configuration changes. Optional arguments can be used to indicate the source and destination datastore. The following use rules apply:
- If no arguments are specified, the diff is performed from the candidate to the baseline of the candidate.
- If a single argument is specified, the diff is performed from the current candidate to the specified candidate.
- If two arguments are specified, the first is treated as the source, and the second as the destination.
Global arguments include: baseline, candidate, checkpoint, factory, file, from, rescue, running, and startup.
The diff command can be used outside of candidate mode, but only if used with arguments.
Example 1:
The following shows a basic diff command without arguments. In this example, the description and admin state of an interface are changed and the differences shown:
Example 2:
The following shows a diff with a single argument. In this example, the comparison occurs to and from a factory configuration.
Example 3:
The following shows an example where the comparison occurs between two checkpoints.
2.3.7. Using the copy command
Use the copy command to copy a specific context to another context. For example, you can use this command to copy a container or any configuration hierarchy and give it another name (such as an interface).
The copy command merges rather than replaces the existing context. If a replace is required, you can delete the target node first. When using the copy command, matching fields populate to the destination node; fields that do not match are ignored. The use of ranges for both source and destination is permitted.
Use this command in candidate mode. Nokia also recommends that you use the diff command to verify changes when using complex copy operations such as multiple ranges in both the source and destination.
Example 1:
The following shows the context of two existing interfaces (ethernet-1/1 and ethernet-2/1):
Example 2:
To copy the context of ethernet-1/1 to ethernet-2/1, enter the following:
Example 3:
The following shows an example where only some fields match. Fields that do not match are ignored:
Example 4:
The following shows an example that uses ranges. The system expands both the source and destination to determine which set has the largest number of keys, and copies 1-to-1 until the larger of the two ranges finishes.
2.3.8. Using the replace command
Use the replace command to replace a source context with a destination context (including all of its children). Both the source and destination can be text. This command can also be used to create a destination that does not currently exist by creating a new key that uses the source configuration.
The replace command has the following usage: replace <original text> with <replacement text>
Use this command in candidate mode.
Example 1:
The following example replaces all instances of the "mgmt" network-instance with a "test" network-instance:
Example 2:
The following example shows a command line that can be used to replaces all instances of "interface lag3" or "aggregate-id lag3" with "interface lag2" or "aggregate-id lag2":
Example 3:
The replace command can also be used with environment alias command so that multiple agruments can be used. In the following, an alias named ‘ifrename’ is created to replace the name of an interface:
Once the alias is created, the alias with the agruments is entered.
For additional information on the use of aliases, see Configuring CLI command aliases.
2.3.9. Displaying configuration details
Use the info command to display the configuration. Entering the info command from the root context displays the entire configuration, or the configuration for a specified context. Entering the command from within a context limits the display to the configuration under that context. Use this command in candidate or running mode.
Example 1:
To display the entire configuration, enter info from the root context:
Example 2:
To display the configuration for a specific context, enter info and specify the context:
Example 3:
From a context, use the info command to display the configuration under that context:
Use the as-json option to display JSON-formatted output:
Example 4:
Use the detail option to display values for all parameters, including those not specifically configured:
Example 5:
Use the flat option to display the output as a series of set statements, omitting indentation for any sub-contexts:
Example 6:
Use the depth option to display parameters with a specified number of sub-context levels:
2.3.10. Displaying the command tree hierarchy
Use the tree command to display the tree hierarchy for all available nodes you can enter. Entering the tree command from the root context displays the entire tree hierarchy. Entering the command from a context limits the display to the nodes under that context.Use this command in candidate or running mode.
2.3.11. Displaying the state of the configuration
To display the state of the configuration, enter the info from state command in candidate or running mode, or the info command in state mode.
Example 1:
To display state information for a specified context from modes that are not state mode:
Example 2:
To display state information for a specified context from state mode:
2.3.12. Executing configuration statements from a file
You can execute configuration statements from a source file consisting of set statements such as those generated by the info flat command (see Displaying configuration details). The SR Linux reads the file and executes each configuration statement line-by-line. You can optionally commit the configuration automatically after the file is read.
Example:
The following example executes a configuration from a specified file:
Use the auto-commit option to commit the configuration after the commands in the source file are executed.
2.3.13. Collecting technical support data
Collect technical support data using the tech-support command. Use this command in any configuration mode.
Example:
You can access the saved file from the bash shell. For example:
2.4. Formatting and filtering CLI output
Several ways exist to format and filter CLI output. These include:
You can .
- Specifying the display output (text, JSON, or table format)
- Filtering the output using Linux tools such as grep
- Using an output filter
- Directing filtered output to a specified file in a specified format
2.4.1. Specifying output format
You can display output from SR Linux CLI commands as lines of text, in JSON format, or in a table. By default, output is displayed as lines of text, but you can configure output to be displayed in JSON format by default. See Configuring the CLI output format.
Example 1:
The following example displays the output of the show version command as lines of text:
Example 2:
The following example displays the output of the show version command in JSON format:
Example 3:
The following example displays the output of the show version command as a table:
2.4.2. Using Linux output modifiers
Output from SR Linux CLI commands can be piped to standard Linux tools, including grep, more, head, and tail.
Example 1:
The following example pipes the output of the show interface command to grep so that only lines with mgmt0 appear in the output:
Example 2:
The following example pipes the output of the show interface command to more to display one page of output at a time:
Example 3:
The following example pipes the output of the show interface command to head to display only the first 8 lines:
2.4.3. Using output filters
You can use the filter option to limit the output of show and info from state commands. Filter options include:
- node - Defines a specific node to filter on
- depth - Filters out sub-nodes that are deeper than the specified depth
- fields - Specifies a specific field or fields to filter on
- keys-only - Hides all fields
- non-zero - Filters integer fields set to 0 and empty strings
The show or info from state command is piped to the filter command with the following usage: filter [<node>] [depth <value>] [fields <value>] [keys-only] [non-zero]
Example 1:
The following example directs the output of the info from state command to filter on the Ethernet node.
Specify the field option to further filter the output to a specific field. For example:
Example 2:
The following example shows how you can use the the non-zero option to display only non-zero values in order to eliminate non-useful information. The use of the non-zero option only filters integer fields that are currently set to 0 and empty strings.
2.4.4. Directing output to a file
You can direct the output of SR Linux CLI commands to a specified file. The output can be saved as text, in table format, or in JSON format.
Example:
The following example directs the output of the show interface command to a file. The output is saved in JSON format.
Use > to create a new file with the specified filename; if the file already exists, it is replaced. Use >> to append the output to the specified file if it exists.
You can access the file using bash mode. For example:
2.5. Customizing the CLI environment
You can optionally configure the SR Linux CLI environment to change settings such as the command prompt, contents of the bottom toolbar, and the default format for displayed output. You can create aliases for CLI commands. The CLI environment settings can be saved to the default SR Linux configuration or to a specified file and subsequently loaded and applied to the current CLI session.
2.5.1. Configuring the CLI prompt
By default, the SR Linux CLI prompt consists of two lines of text, indicating with an asterisk whether the configuration has been modified, the current mode and session type, the current CLI context, and the host name of the SR Linux device, in the following format:
Example 1:
You can configure the SR Linux prompt to include information such as the user name or session ID of the CLI session, the number of changes made to the configuration, and the current local time.
Example 2:
The following example adds the local time and session user name to the SR Linux CLI prompt.
In the example, the local time is configured with the {time} keyword, and the session user name is configured with the {user} keyword. The line break is configured with \n. Use the environment prompt ? command to display the keywords that you can configure in the SR Linux CLI prompt.
After you enter this command, the CLI prompt looks like the following:
2.5.2. Configuring the bottom toolbar text
By default, the text that appears at the bottom of the terminal window in SR Linux CLI sessions displays the current mode and session type, whether the configuration has been modified, the user name and session ID of the current AAA session, and the local time, in the following format:
For example:
You can configure the bottom toolbar to include information such as the number of changes made to the configuration and the host name.
Example 1:
The following example adds the number of changes made to the configuration and the host name to the bottom toolbar.
In the example, the number of configuration changes is configured with the {modified_with_change_count} keyword, and the host name is configured with the {host} keyword. Use the environment bottom-toolbar ? command to display the keywords that you can configure in the bottom toolbar.
After you enter this command, the bottom toolbar looks like the following:
2.5.3. Configuring the SR Linux CLI engine type
The SR Linux features two versions of the CLI engine: advanced and basic. The advanced CLI engine is enabled by default; it includes the following features:
- Displays a toolbar at the bottom of the terminal window. See Configuring the bottom toolbar text.
- Includes the command auto-complete feature, as described in Using the CLI auto-complete function.
- Allows you to select command options by pressing the Tab key to display the options in a popup, then using the arrow keys to select an option.
- Displays descriptions of command options when you press the ? key.
The basic CLI engine includes a limited set of features compared to the advanced version:
- Omits the bottom toolbar.
- Does not present a selectable list of options when you press the Tab key.
- Displays descriptions of command options when you press the ? key (and press Enter), but only at the # prompt for the current context.
If necessary, you can configure the SR Linux to use the basic CLI engine instead of the advanced CLI engine for CLI sessions.
Example:
The following example configures the SR Linux to use the basic CLI engine for CLI sessions:
2.5.4. Configuring the CLI output format
You can configure the output of CLI commands to be displayed as either text or in JSON format.
Example:
The following example configures CLI command output to be displayed in JSON format.
Subsequent command output is displayed in JSON format by default. For example:
2.5.5. Configuring CLI command aliases
As a shortcut for entering commands in the CLI, you can configure CLI command aliases. The alias can include one or more CLI command keywords and arguments.
Example:
The following example configures the alias display interface for the SR Linux command info interface <name> subinterface <index> | as table:
In the example, the display interface alias consists of the keywords info interface, arguments to specify an interface name and subinterface number, and keywords to display the output as a table. The alias name and aliased command are each enclosed in quotes. The arguments are enclosed in braces ({ }). The argument {} creates an optional unnamed variable for the interface name, and the argument {subinterface} creates an optional parameter named subinterface.
When you enter the alias at the CLI prompt, the output of the aliased command is displayed. For example:
If you omit the optional parameters for the interface and subinterface names, they are treated as wildcards. For example:
2.5.6. Configuring command auto-completion
By default, if you enter a tab at any mode or level to auto-complete the next command level, a popup appears that displays the available options for that command. See Using the CLI auto-complete function.
You can optionally configure the space bar to provide the same function as the Tab key, so that pressing the space bar auto-completes the command.
Example:
The following example configures the space bar to auto-complete commands in SR Linux CLI sessions:
2.5.7. Displaying the CLI environment configuration
To display the CLI environment configuration, including any CLI command aliases, use the environment show command.
Example:
2.5.8. Managing CLI environment settings
You can save the current CLI environment settings to the default SR Linux configuration or to a file, and you can load CLI environment settings from the default SR Linux configuration or from a file.
Example 1:
The following example saves the current CLI environment settings to the default SR Linux configuration:
Example 2:
The following example saves the current CLI environment settings to a file:
Example 3:
The following example loads CLI environment settings from the default SR Linux configuration:
Example 4:
The following example loads CLI environment settings from a file: