Using the Advanced Routing Suite CLI

This chapter explains how to start and use the CLI in different modes.

Starting the Advanced Routing Suite CLI

Be sure no other users are connected to Advanced Routing Suite. With Advanced Routing Suite installed properly and running:

1. Enter the SecurePlatform expert mode.
2. Type pro enable at the prompt and press Enter.
3. Reboot.
4. Type router at the prompt and press Enter.

This begins your CLI session in User Execution mode.

The Advanced Routing Suite CLI can be started with several additional command line options. These options include the following:

• -p
• -f
• -l
• -a
• -s

The -p option

-p <port>

The -p option specifies the port on which Advanced Routing Suite's XML subsystem is listening. The argument to this option must be a valid port number. If the -p option is not specified, then the CLI assumes that Advanced Routing Suite's XML subsystem is listening on port 4242.

The -f option

-f <cmd_fname>

The -f option specifies a file from which CLI commands are to be read after the CLI has initialized.

The -e option

-e [ ( s || c || e || w || d || i ) | 0 | all ]

The -e option specifies the event class or classes that the CLI will log. The arguments have the following meanings:

s - Trace security events

c - Trace user-typed commands

e - Trace errors

w - Trace internal warnings and errors

d - Trace debugging events

i - Trace informational events

0 - Trace no events

all - Trace all event sets

Default

If the -e option is not specified, it is the same as if -e wg were specified.

The -a option

-a [ o | a | m ]

The -a option specifies the action to take if you want a log file, and a cli.log file already exists in the location specified by the -l option. Available arguments include the following:

o - Overwrite the existing cli.log file

a - Append to the existing cli.log file

m - Move the existing cli.log file to cli.log.x, where x is the next highest integer among the other files named cli.log.* in the logging directory.

Default

If -a is not specified, then it is as if -a a were specified.

The -s option

-s <size_num>[k | m]

The -s option specifies the maximum size of the CLI log in either kilobytes or megabytes. The action to take when the current log's maximum size is reached is determined by the -a option.

Default

If the -s option is not specified, then it is as if -s 5m were specified.

Basic Features

Basic features of the Advanced Routing Suite CLI include the following:

• Command Tokens
• Command Line Completion
• Moving About the Command Line
• Context-Sensitive Help
• Command History
• Disabling/Enabling CLI Logging
• Aborting an Executing Command
• Exiting the CLI

Command Tokens

The Advanced Routing Suite CLI command strings are composed of space-delimited tokens. The maximum number of tokens permitted per line is 32. After a full command line is typed, the Enter key sends the line to the CLI for processing. The CLI is case insensitive.

Command Line Completion

The max number of characters per line is 1024. At any point when typing a command line, you can hit the Tab key to either complete the current command token or show a list of possible completions. Consider the following command structure as an example:

abc
| |
--------
| |
bar groove
| |
-------
| |
par-name1 par-name2
| |
number number

The valid complete command strings are the following:

abc groove

abc bar par-name1 [number]

abc bar par-name2 [number]

With command line completion, when you type

ab<Tab>

the command will be completed as abc on the same line because no other legal token begins with "ab".

When you type

abc bar <Tab>

the CLI will display the tokens that can follow bar on a separate line, then re-display your typed line as shown below. Note that "routerz>" is the Advanced Routing Suite CLI prompt, with "routerz" being the name of the machine on which Advanced Routing Suite is running.

routerz> abc bar <Tab>
par-name1 par-name2
routerz> abc bar

Valid commands are not required to be composed of complete tokens. Only a token's smallest unique abbreviation is required. For example, the following two command strings are equivalent:

abc bar par-name1 20

a b par-name1 20

If the abbreviation is not unique, the CLI will respond with an "Invalid command" error.

Moving About the Command Line

The curser does not need to be at the end of a command line before hitting the Enter key. In the examples below, the underscore indicates the position of the curser.

routerz> abc bat bas_

If, in the example above, you intended to type "abc bar bas", move the left arrow key back to the space following "bat", delete the "t", and type "r".

routerz> abc bar_bas

With the curser still just right of the "r", you can still hit the ENTER key, and the complete line will be given to the CLI for processing.

Context-Sensitive Help

Type "?" immediately after any token to obtain context-sensitive help about the last command that you typed. For example requesting help immediately after typing "router" shows you that the command enters router mode:

(config)#router?

router Enter router mode

Type "?" followed by a space after any set of tokens to obtain a list of options that can be used in the command. For example, if you type the following:

(config)# router ?

the CLI will respond with the following:

aggregate Configure Aggregate/Generate routes
bgp Configure BGP
icmp Configure ICMP
ospf Configure OSPF
rip Configure RIP

(config)# router

If "router" was not a valid sequence of tokens (or, if it was misspelled), then the CLI would respond with an "Error completing word" error.

(config)#access-list an?

<name> Name of an access list

History

All commands entered during a CLI session are saved in a command history. The command history can be viewed and with short-hand "!" commands. The history can be toggled on and off.

Disabling/Enabling CLI Tracing

The CLI provides a flexible tracing mechanism. Events to be traced are divided into several classes, each of which can be traced individually. Classes can be traced to any or all three of the following locations: the terminal, a file, or the underlying system's tracing system (i.e., syslog).

Aborting an Executing Command

It may sometimes be desirable to abort a query that generates a lot of output. Typing Ctrl+C generates such an abort signal and flushes any queued input.

Screen Paging

If a response to a command contains more lines than provided by the command line window, then the word "more" appears at the bottom of the screen to indicate that not all lines have been displayed. Press the Space bar to display more lines. To stop viewing the output and return to the command line prompt, press any other key.

Exiting the CLI

Changes are saved as soon as you hit "Enter" after a command. Use the "quit" command to exit the CLI.

CLI Modes

The Advanced Routing Suite CLI has the following five modes:

• User Execution
• Privileged Execution
• Global Configuration
• Router Configuration
• Interface Configuration

The current mode is easily discerned by examining the current command line prompt. The CLI prompt always indicates the current mode. The modes and prompts are described in the sections that follow.

User Execution M ode

User Execution mode is the default mode that the CLI assumes when it begins execution. In User Execution mode, the prompt is ">".

Within User Execution mode, the following actions are allowed:

• Querying of Advanced Routing Suite configuration state
• Querying of dynamic protocol state (for example, the number of OSPF neighbors)
• Modification of various CLI options, such as command history length, CLI events to trace, and so on.

Privileged Execution M ode

Privileged Execution mode allows for "privileged" commands. In Privileged Execution mode, the prompt is "#". This mode is password protected and is entered using enable as follows:

routerz> enable
Password: [password]
routerz#

Use the disable command to leave Privileged Execution mode and return to User Execution mode.

Global Configuration M ode

Global Configuration mode is used to change the configuration of Advanced Routing Suite. From this mode, you can stop and start protocols and set protocol-specific parameters. This mode can only be entered from Privileged Execution mode with the configure terminal command. When this mode is entered, the prompt changes to "(config)#" as shown below.

routerz> enable
Password: [password]
routerz# configure terminal
routerz(config)#

Unless otherwise noted, configuration changes that are entered in this mode are made immediately upon hitting Enter.

To exit Global Configuration mode and return to Privileged Execution mode, use the "exit" or "end" command or type "Ctrl+Z". All three are synonymous.

routerz(config)# end
routerz#

Router Configuration Mode

Router Configuration mode is used to change the protocol state on a specific router. This mode is entered by typing the following at the (config)# prompt:

router protocol_name

For example, type the following to enter Router Configuration mode for the ICMP protocol:

routerz(config)# router icmp
routerz(config-icmp)#

The prompt changes to "(config-[protocol_name])#" in Router Configuration mode. To exit Router Configuration mode and return to Global Configuration mode, use the "exit" command.

routerz(config-icmp)# exit
routerz(config)#

Interface Configuration M ode

Interface Configuration mode is used to change protocol state on a specific interface. This mode is entered by typing the following at the (config)# prompt:

interface [ if-type if-number | if-name ]

For example, type the following to enter Interface Configuration mode for the physical interface named ppp-interface-0:

routerz(config)# interface ppp-interface-0
routerz(config-if)#

The prompt changes to "(config-if)#" in Interface Configuration mode. To exit Interface Configuration mode and return to Global Configuration mode, use the "exit" command.

routerz(config-if)# exit
routerz(config)#

CLI Behavior Commands

The section describes the commands that control the CLI behavior, as opposed to commands that control Advanced Routing Suite behavior.

configure file

Syntax

configure file [filename | replace filename]

Mode

Privileged Execution

Parameters

filename - the name and/or path of the configure file

replace filename - specifies to replace the current configuration file with the specified filename

Description

The configure file command is used to enter an atomic batch mode, where configuration commands are read from the named file or replace with the named file. If any errors are encountered during processing of the named file, then the router's configuration is left unchanged. The filename argument to file can be either a fully or partially qualified name. A fully qualified file name begins with "/" and gives the complete path to the file in addition to the file name. A partially qualified file name does not begin with"/" and may indicate path information in addition to the file name. If path information is given, it is interpreted with respect to the CLI's working directory.

Examples

In the following example, configuration commands are read from the file, /etc/routerz.cfg.

routerz# configure file /etc/routerz.cfg
routerz#

configure terminal

Syntax

configure terminal

Mode

Privileged Execution Mode

Description

Use the configure terminal command in Privileged Execution mode to enter Global Configuration mode and change the router's configuration. This command takes one of two parameters. The "#" prompt changes to "(config)#" to indicate the changed mode. Use the "end" command to leave Global Configuration mode.

Examples

In the following example, configuration commands are entered from the terminal.

routerz# configure terminal
routerz(config)# terminal history size 1024
routerz(config)# end
routerz#

disable

Syntax

disable

Mode

Privileged Execution

Description

Use the disable command to leave Privileged Execution Mode and re-enter User Execution mode.

Examples

routerz# disable
routerz>

enable

Syntax

enable

Mode

User Execution

Description

Use the enable command to enter Privileged Execution mode from User Execution mode. The # prompt indicates that the current mode is Privileged Execution mode.

Examples

routerz> enable
Password: abcdefg
routerz#

end

Syntax

end

Mode

Global Configuration

Description

Use the end command to leave Global Configuration mode and return to Privileged Execution mode.

Examples

routerz(config)# end
routerz#

exit

Syntax

exit

Mode

Interface Configuration

Global Configuration

Description

Use the exit command to leave Interface Configuration mode and return to Global Configuration mode. Or, use exit to leave Global Configuration mode and return to Privileged Execution mode. Finally, use exit to leave Router Configuration mode and return to Global Configuration mode.

Examples

routerz(config-if)# exit
routerz(config)#

or

routerz(config)# exit
routerz#

ip router-id

Syntax

ip router-id ipv4 address

Mode

Global Configuration

Parameters

ipv4_address - a valid IPv4 address

Description

Use the ip router-id command to configure the global Router ID. This router ID can be overridden in BGP, OSPF, and OSPF3.

Examples

routerz(config)# ip router-id 1.1.1.1
routerz(config)#

ip routingtable-id

Syntax

ip routingtable-id id

Mode

Global Configuration

Parameters

id - an integer from 0 to 250, inclusive

Description

Use the ip routingtable-id command to configure an ID for the routing table. When there is no kernel VRF support, this ID is used to decide the kernel routing table to which Advanced Routing Suite will write.

Examples

routerz(config)# ip routingtable-id 200
routerz(config)#

logout

Syntax

logout

Mode

User Execution

Description

Use the logout command to exit the CLI. This command is synonymous with exit.

Examples

The following example logs you out of the CLI.

routerz> logout
%

quit

Syntax

quit

Mode

User Execution

Description

Use the quit command to exit the CLI. This command is synonymous with logout.

Examples

The following example exits you out of the CLI. Note that the "%" prompt is intended to indicate the shell command line prompt. The prompt can be different, depending on the shell and shell settings from which the Advanced Routing Suite CLI was started.

routerz> quit
%

show debugging

Syntax

show debugging

Mode

User Execution

Privileged Execution

Global Configuration

Interface Configuration

Description

This command is used to report information that is of use mainly to developers.

Examples

routerz> show debugging
...debugging output...
routerz>

show history

Syntax

show history

Mode

User Execution

Privileged Execution

Global Configuration

Interface Configuration

Description

Use show history in any mode to display the commands that have been entered during the current session. The format of the history lines is as follows:

command number time-stamp command

command number represents the sequential number of the command. The most recent command displays with the highest number. time-stamp displays the time when the command was entered. Finally, command shows the command that was entered.

To re-run the most recent command, type !!, and press Enter.

To re-run a specific command appearing in the history list, type !<number>, where <number> is the command number as it appears in the output of a show history command.

Examples

Example 1

In the following example, several commands are entered. The command history is then displayed.

routerz> enable
Password: abcdefg
routerz# configure terminal
routerz(config)# interface fxp0
routerz(config-if)# ip igmp robustness 2
routerz(config-if)# show history
0 09:15:02 enable
1 09:15:48 configure terminal
2 09:16:12 interface fxp0
3 09:17:03 ip igmp robustness 2
4 09:17:50 show history
routerz(config-if)#

Example 2

In the following example, several commands are entered, followed by a show history command. Finally, a short-hand ! command is used to re-run a previous command.

routerz> enable
Password: abcdefg
routerz# configure terminal
routerz(config)# interface fxp0
routerz(config-if)# ip rip metric-in 2
routerz(config-if)# Ctrl+z
routerz# show history
0 10:24:10 enable
1 10:25:17 configure terminal
2 10:26:48 interface fxp0
3 10:27:08 ip rip metric-in 2
4 10:28:00 Ctrl+z
5 10:28:22 show history
routerz(config-if)# !3

show running-config

Syntax

show running-config

Mode

Privileged Execution

Description

The show running-config command reports the active configuration.

Examples

The following example shows output for a request for all configuration information.

routerz# show running-config
Building configuration...

Current configuration : 966 bytes
!
version 12.2
service password-encryption
!
hostname router-abc
!
enable password 7 011204070A59554E
!
ip subnet-zero
!!
ip multicast-routing
!
interface Ethernet0/0
ip address 10.139.10.26 255.128.0.0
ip pim bsr-border
ip pim sparse-mode
half-duplex
!
interface Serial0/0
ip address 10.11.41.21 255.255.255.252
!
interface Ethernet0/1
ip address 10.11.111.26 255.255.255.0
ip pim sparse-mode
!
router ospf 7
log-adjacency-changes
!
router bgp 7
bgp log-neighbor-changes
!
ip default-gateway 10.254.10.1
ip classless
ip route 0.0.0.0 0.0.0.0 10.254.10.1
no ip http server
ip ospf name-pookup
!
access-1ist 1 permit 224.0.0.0 15.255.255.255
!
!end

routerz#

show version

Syntax

show version

Mode

User Execution

Privileged Execution

Description

This command displays the version of the Advanced Routing Suite CLI as well as the version of Advanced Routing Suite.

Examples

The following example is a request to determine the version of Advanced Routing Suite currently running.

routerz> show version
CLI version: 1.1

GateD version: ngc 2.3

AMI API version: 2
routerz>

terminal history

Syntax

terminal history

terminal no history

Mode

User Execution

Privileged Execution

Global Configuration

Interface Configuration

Description

The terminal history command can be used in any mode to turn on command line history. The terminal no history command turns off command line history.

Examples

In the following example, command line history is turned on with the first command. Several commands are then entered, followed by a command to turn the command line history off.

routerz> terminal history
routerz> configure terminal
routerz(config)# interface 10.10.11.1
routerz(config-if)# ip dvmrp metric-offset in 2
routerz(config-if)# exit
routerz(config)# interface fxp0
routerz(config-if)# ip rip metric-in 1
routerz(config-if)# exit
routerz(config)# terminal no history

terminal history size

Syntax

terminal history size num-lines

Mode

User Execution

Privileged Execution

Global Configuration

Interface Configuration

Description

Use the terminal history size command in any mode to set the maximum number of lines that are remembered in the command line history. The default size of the command line history buffer is 1000 lines. The valid range is from 0 to 10,000, inclusive.

Examples

The following example sets the command line history buffer to 10 lines.

routerz> terminal history size 10

terminal length

Syntax

terminal length num-lines

Mode

User Execution

Privileged Execution

Global Configuration

Interface Configuration

Description

Use the terminal length command in any mode to specify the number of lines that display on a page. The number of lines defaults to the length of your screen. The valid range for length is 0 to 4,294,967,295, inclusive.

Examples

The following example sets the number of displayed lines to 40 lines.

routerz> terminal length 40

write memory

Syntax

write memory

Mode

Privileged Execution

Description

Use the write memory command in Privileged Execution mode to write the current Advanced Routing Suite config file for use at startup.

Examples

The following example configures write memory.

routerz# write memory

Querying the Advanced Routing Suite CLI

Use the Advanced Routing Suite queries to request information about a CLI session. Both the candidate and the committed configurations can be queried at any time during a CLI session. Unless otherwise specified, queries can be issued for the entire configuration hierarchy or a subtree of the hierarchy. Protocol-specific query information is available in each chapter. Queries can also be performed to determine memory and task information.

Memory Information

Use the show memory query to obtain information about Advanced Routing Suite's current memory usage.

Syntax

show memory

Parameters

none

Description

The show memory query displays information about Advanced Routing Suite's current memory usage.

Examples

The following example displays a response for the show memory query.

> show memory

Block Name: "nospf_if_head_t"
Block Size: 4
Freelist Length: 1005
Num Init Requests: 1
Num Alloc Requests: 0
Num Free Requests: 0
Num blocks in use: 0
Num bytes in use: 0

Total bytes consumed: 56516
Total bytes in use: 159692
Num block alloc calls: 53767
Min used block size: 4
Page size: 4096
Num of pages allocated: 4096
Num task block malloc pages: 155
Num task block alloc pages: 28
Multipage max alloc: 41
Multipage max reused: 86
Task page alloc multiq: 5
Task block reclaim shreds: 0
Task block reclaim unmaps: (null)
Num multipage pages in use: 95
Num pool alloc pages: 0
Growable array information:
Num of growable arrays: 33
Num of growths: 7
Max allocation: 256
Num malloc calls: 1400
Num calloc calls: 7
Num reallocs: 2532
Num reallocs for more: 11462
Num reallocs for less: 27
Num reallocs for same: 8
Num free-calls: 8
Num bytes requested: 0
Num bytes allocated: 0
Num bytes wasted: 11240
Max outstanding allocs: 41932
Max request: 59848
Num outstanding allocs: 17632

Field Descriptions

The following table describes the fields that appear in the Show Memory Query.

Show Memory Query Fields

Task Information

Use the show task query to obtain information about currently active Advanced Routing Suite tasks.

Syntax

show task

Parameters

none

Description

The show task query displays information about currently active Advanced Routing Suite tasks.

Examples

The following example displays a response for the show task query.

> show task

Task Name: "IF"
Task Proto Number: N/A
Task Priority: 10
Task Address: N/A
Task Port: N/A
Task Socket: N/A
Task RT Proto Bit: Direct
Task Flags:
Accept: no
Connect: no
Delete: no
Low-Priority: no

Field Descriptions

The following table describes the fields that appear in the Show Memory Information Query.

Show Memory Information Query Fields

General Concepts

Address and Prefix Formats

Advanced Routing Suite allows configuration of IPv4 address types only. Normally Advanced Routing Suite can recognize which type of address is being configured in a particular instance by the format of the address.

IPv4 addresses are 32 bits long. The formats of IPv4 addresses recognized by Advanced Routing Suite are:

d

d.d

d.d.d

d.d.d.d

where d represents a number in the range 0-255 inclusive. Each d specifies 8 bits of the address. If fewer than four d values are provided then the values provided specify the high order values of the address. For example, 192.168 is equivalent to 192.168.0.0.

In many cases IPv4 addresses are combined with masks to configure prefixes. There are two methods for specifying the mask: It can be specified as an IPv4 address proceeded by the mask keyword; or it can be specified as a length proceeded by the masklen keyword or, more conventionally, by a '/'. In the "mask" case, the address type of the mask must match the address type. Currently only contiguous bit masks are allowed in Advanced Routing Suite. Any non-zero address bits in positions that are covered by the specified mask cause a parse error. Example prefix specifications are:

10/8

10.0.0.0 mask 255.0.0.0 (equivalent to 10/8)

10 masklen 8 (equivalent to 10/8)

0/0 (IPv4 default address)

192.168.1/16 (invalid because the .1 is not covered by the mask)

Preferences Overview

Preference is the value that Advanced Routing Suite uses to select one route over another when more than one route to the same destination is learned from different protocols or peers. Preference can be set in the Advanced Routing Suite configuration files in several different configuration statements. Preference can be set based on one network interface over another, one protocol over another, or one remote gateway over another. Preference cannot be used to control the selection of routes within an interior gateway protocol. This control is accomplished automatically by the protocol based on metric. Preference can be used to select routes from the same exterior gateway protocol (such as BGP) learned from different peers or autonomous systems. Each route has only one configurable preference value associated with it, even though preference can be set at many places in the configuration file. Simply, the last or most specific preference value set for a route is the value used. Preference can also be used to select one IGP instance over another.

The preference value is an arbitrarily assigned value used to determine the order of routes to the same destination in a single routing database. The active route is chosen by the lowest preference value. Some protocols implement a second preference (preference2), sometimes referred to as a tie-breaker. BGP and OSPF protocols use preference2. For OSPF, preference2 is for internal use only and is not configurable. For BGP, preference2 can be configured. Its value is used only when comparing routes with equal values of preference.

Assigning Preferences

A default preference is assigned to each source from which Advanced Routing Suite receives routes. Preference values range from 1 to 255, with the lowest number indicating the most preferred route.

The following table summarizes the default preference values for routes learned in various ways. The table lists the statements (some of which are clauses within statements) that set preference and shows the types of routes to which each statement applies. The table lists the preference precedence between protocols and the default preference for each type of route. The more narrow the scope of the statement, the higher the precedence its preference value is given, but the smaller the set of routes it affects.

Preference Selection Precedence