To interact with a XORP router using the command line interface (CLI), the user runs the XORP command shell “xorpsh”. This allows configuration of the router and monitoring of the router state. In this chapter we describe how to interact with xorpsh. In later chapters we describe the details of how to configure BGP, PIM, SNMP and other processes. The user interface style is loosely modelled on that of a Juniper router. This manual and the xorpsh itself are works in progress, and so may change significantly in the future.
The xorpsh command provides an interactive command shell to a XORP user, similar in many ways to the
role played by a Unix shell. In a production router or on the XORP LiveCD, xorpsh might be set up as
an user’s login shell - they would login to the router via ssh and be directly in the xorpsh environment.
However, for research and development purposes, it makes more sense to login normally to the machine
running the XORP processes, and to run xorpsh directly from the Unix command line.
xorpsh should normally be run as a regular user; it is neither necessary or desirable to run it as root. If an
user is to be permitted to make changes to the running router configuration, that user needs to be in the Unix
group xorp. The choice of GID for group xorp is not important.
xorpsh needs to be able to communicate with the XORP router management process xorp rtrmgr using the
local file system. If the xorp rtrmgr cannot write files in /tmp that xorpsh can read, then xorpsh will not be
able to authenticate the user to the xorp rtrmgr.
Multiple users can run xorpsh simultaneously. There is some degree of configuration locking to prevent
simultaneous changes to the router configuration, but currently this is fairly primitive.
To facilitate automated XORP router configuration, it is possible to use xorpsh in non-interactive mode (e.g.,
as part of a shell script). This is described in details in Running xorpsh in Non-Interactive Mode.
On starting xorpsh, you will be presented with a command line prompt:
user@hostname>
You can exit xorpsh at any time by trying Control-d. Typing “?” at the prompt will list the commands currently available to you:
user@hostname> ? Possible completions: configure Switch to configuration mode exit Exit this command session help Provide help with commands quit Quit this command session show Display information about the system
If you type the first letter or letters of a command, and hit <Tab>, then command completion will occur.
At any time you can type “?” again to see further command completions. For example:
user@hostname> config? Possible completions: configure Switch to configuration mode user@hostname> config
If the cursor is after the command, typing “?” will list the possible parameters for the command:
user@hostname> configure ? Possible completions: <[Enter]> Execute this command exclusive Switch to configuration mode, locking out other users user@hostname> configure
xorpsh supports emacs-style command history and editing of the text on the command line. The most important commands are:
The xorpsh command output is displayed on the screen that is running xorpsh. If the command output can
fit within the screen, it is printed followed by the XORP prompt so the user can input new commands.
If the command output is too large to fit, the xorpsh uses the UNIX more-like interface to display it one
screen at a time. In that case the bottom of the display shows a –More– prompt. If the screen displays the
end of the output, the prompt is –More– (END). Typing ’h’ at the –More– prompt can be used to display
help information about available commands:
SUMMARY OF MORE COMMANDS
-- Get Help --
h * Display this help.
-- Scroll Down --
Enter Return j * Scroll down one line.
^M ^N DownArrow
Tab d ^D ^X * Scroll down one-half screen.
Space ^F * Scroll down one whole screen.
^E G * Scroll down to the bottom of the output.
N * Display the output all at once instead of one
screen at a time. (Same as specifying the
| no-more command.)
-- Scroll Up --
k ^H ^P * Display the previous line of output.
UpArrow
u ^U * Scroll up one-half screen.
b ^B * Scroll up one whole screen.
^A g * Scroll up to the top of the output.
-- Misc Commands --
^L * Redraw the output on the screen.
q Q ^C ^K * Interrupt the display of output.
--More-- (END)
The output of a xorpsh command can be filtered or modified by applying various filter commands. If a xorpsh command allows its output to be filtered, then displaying help about such command will list the UNIX-like pipe command ’|’ as one of the options:
user@hostname> show host date | ? Possible completions: count Count occurrences except Show only text that does not match a pattern find Search for the first occurrence of a pattern hold Hold text without exiting the --More-- prompt match Show only text that matches a pattern no-more Don’t paginate output resolve Resolve IP addresses (NOT IMPLEMENTED YET) save Save output text to a file (NOT IMPLEMENTED YET) trim Trip specified number of columns from the start line (NOT IMPLEMENTED YET)
xorpsh has two command modes:
| Command Mode | Description |
|---|---|
| Operational Mode | Allows interaction with the router to monitor its operation and status. |
| Configuration Mode | Allows the user to view the configuration of the router, to change that configuration, and to load and save configurations to file. |
Generally speaking, operational mode is considered to give non-privileged access; there should be nothing an user can type that would seriously impact the operation of the router. In contrast, configuration mode allows all aspects of router operation to be modified.
In the long run, xorpsh and the xorp_rtrmgr will probably come to support fine-grained access control, so
that some users can be given permission to change only subsets of the router configuration. At the present
time though, there is no fine-grained access control.
xorp Unix group.
user@hostname> ? Possible completions: configure Switch to configuration mode exit Exit this command session help Provide help with commands quit Quit this command session show Display information about the system
The main commands in operational mode are:
| Command | Description |
|---|---|
| configure | Switches from operational mode to configuration mode. |
| exit | Exit from xorpsh. |
| help | Provides online help. |
| quit | Quit from xorpsh. It is equivalent to the exit command. |
| show | Displays many aspects of the running state of the router. |
user@hostname> show ? Possible completions: bgp Display information about BGP host Display information about the host igmp Display information about IGMP interfaces Show network interface information mfea Display information about IPv4 MFEA mfea6 Display information about IPv6 MFEA mld Display information about MLD pim Display information about IPv4 PIM pim6 Display information about IPv6 PIM rip Display information about RIP route Show route table version Display system version user@hostname> show
The show command is used to display many aspects of the running state of the router. We don’t describe the
sub-commands here, because they depend on the running state of the router. For example, only a router that
is running BGP should provide show bgp commands.
As an example, we show the peers of a BGP router:
user@hostname> show bgp peers detail OK Peer 1: local 192.150.187.108/179 remote 192.150.187.109/179 Peer ID: 192.150.187.109 Peer State: ESTABLISHED Admin State: START Negotiated BGP Version: 4 Peer AS Number: 65000 Updates Received: 5157, Updates Sent: 0 Messages Received: 5159, Messages Sent: 1 Time since last received update: 4 seconds Number of transitions to ESTABLISHED: 1 Time since last entering ESTABLISHED state: 47 seconds Retry Interval: 120 seconds Hold Time: 90 seconds, Keep Alive Time: 30 seconds Configured Hold Time: 90 seconds, Configured Keep Alive Time: 30 seconds Minimum AS Origination Interval: 0 seconds Minimum Route Advertisement Interval: 0 seconds
user@hostname> configure Entering configuration mode. There are no other users in configuration mode. [edit] user@hostname#
When in configuration mode, the command prompt changes from user@hostname> to user@hostname#.
The command prompt is also usually preceded by a line indicating which part of the configuration tree is
currently being edited.
[edit] user@hostname# ? Possible completions: commit Commit the current set of changes create Alias for the ‘‘set’’ command (obsoleted) delete Delete a configuration element edit Edit a sub-element exit Exit from this configuration level help Provide help with commands load Load configuration from a file quit Quit from this level run Run an operational-mode command save Save configuration to a file set Set the value of a parameter or create a new element show Show the configuration (default values may be suppressed) top Exit to top level of configuration up Exit one level of configuration user@hostname#
The router configuration has a tree form similar to the directory structure on a Unix filesystem. The current configuration or parts of the configuration can be shown with the show command:
[edit]
user@hostname# show interfaces
interface rl0 {
description: "control interface"
vif rl0 {
address 192.150.187.108 {
prefix-length: 25
broadcast: 192.150.187.255
}
}
}
Note that the show command suppresses parameters that have default values (as specified in the corresponding router manager template files). Use command show -all to show the complete configuration including the parameters with default values:
[edit]
user@hostname# show -all interfaces
interface rl0 {
description: "control interface"
vif rl0 {
address 192.150.187.108 {
prefix-length: 25
broadcast: 192.150.187.255
disable: false
}
disable: false
}
disable: false
discard: false
unreachable: false
management: false
}
targetname: "fea"
You can change the current location in the configuration tree using the edit, exit, quit, top and up commands.
| Command | Description |
|---|---|
| edit <element name> | Edit a sub-element. |
| exit | Exit from this configuration level, or if at top level, exit configuration mode. |
| quit | Quit from this level. |
| top | Exit to top level of configuration. |
| up | Exit one level of configuration. |
For example:
[edit]
user@hostname# edit interfaces interface rl0 vif rl0
[edit interfaces interface rl0 vif rl0]
user@hostname# show
address 192.150.187.108 {
prefix-length: 25
broadcast: 192.150.187.255
}
[edit interfaces interface rl0 vif rl0]
user@hostname# up
[edit interfaces interface rl0]
user@hostname# top
[edit]
user@hostname#
On startup, the xorp rtrmgr will read a configuration file. It will then start up and configure the various router components as specified in the configuration file. The configuration file can be created externally, using a normal text editor, or it can be saved from the running router configuration. A configuration file can also be loaded into a running router, causing the previous running configuration to be discarded. The commands for this are:
| save <filename> | save the current configuration in the specified file. |
|---|---|
| load <filename> | load the specified file, discarding the currently running configuration. |
The <filename> argument may be a path to a disk file, or an Uniform Resource Identifier (URI) with a
scheme of file, ftp, http, or tftp. The xorp_rtrmgr does not know how to deal with these schemes on its own;
external commands are invoked to perform the actual save or load operation. If an URI is used to save or
load the router configuration, then the appropriate variables must be set in the rtrmgr block to point to these
commands. Commands are invoked with the following arguments:
Note that currently no commands or scripts to perform these operations are shipped with XORP. For example:
rtrmgr {
load-tftp-command: "/usr/local/sbin/xorp-tftp-get.sh"
load-tftp-command-args: "-o"
save-tftp-command: "/usr/local/sbin/xorp-tftp-put.sh"
save-tftp-command-args: "-i"
}
Then, if the user uses xorpsh command load tftp:hostname/path/to/config.boot to load the configuration,
internally the xorp_rtrmgr will use the following command:
/usr/local/sbin/xorp-tftp-get.sh -o <tmp-filename> tftp:hostname/path/to/config.boot
This command will download the configuration file to a temporary file (chosen internally by the xorp rtrmgr) on the local filesystem and then the xorp rtrmgr will load the configuration from that temporary file before deleting it.
Similarly, if the user uses xorpsh command save tftp:hostname/path/to/config.boot to save the configuration, internally the xorp_rtrmgr will use the following command:
/usr/local/sbin/xorp-tftp-put.sh -i <tmp-filename> tftp:hostname/path/to/config.boot
First, the xorp rtrmgr will save the configuration to a temporary file (chosen internally by the xorp rtrmgr)
on the local filesystem. Then the /usr/local/sbin/xorp-tftp-put.sh command will be used to upload that file.
Finally, the xorp_rtrmgr will delete the temporary file.
| set <path to config> <value> | set the value of the specified configuration node. |
|---|
The set command can be used to set or change the value of a configuration option. The change does not actually take effect immediately - the commit command must be used to apply this and any other uncommitted changes. In the example below, the prefix length (netmask) of address 192.150.187.108 on vif rl0 is changed, but not yet committed. The “>” indicates parts of the configuration that has been added or modified but not yet been committed.
[edit interfaces interface rl0]
user@hostname# show
description: "control interface"
vif rl0 {
address 192.150.187.108 {
prefix-length: 25
broadcast: 192.150.187.255
}
}
[edit interfaces interface rl0]
user@hostname# set vif rl0 address 192.150.187.108 prefix-length 24
OK
[edit interfaces interface rl0]
user@hostname# show
description: "control interface"
vif rl0 {
address 192.150.187.108 {
> prefix-length: 24
broadcast: 192.150.187.255
}
}
| set <path to new config node> | create new configuration node. |
|---|---|
| set <path to new config node> { | create new configuration node and start editing it. |
New configuration can be added by the set command.1) If we type set followed by the path to a new configuration node, the node will be created. All parameters within that node will be assigned their default values (if exist). After that the node can be edited with the edit command. If we type { after the path to the new configuration node, the node will be created, the default values will be assigned, and we can directly start editing that node. The user interface for this is currently rather primitive and doesn’t permit the more free-form configuration allowed in configuration files.
For example, to configure a second address on interface/vif rl0:
[edit interfaces interface rl0 vif rl0]
user@hostname# show
address 192.150.187.108 {
prefix-length: 24
broadcast: 192.150.187.255
}
[edit interfaces interface rl0 vif rl0]
user@hostname# set address 10.0.0.1 {
> prefix-length 16
> broadcast 10.0.255.255
> }
[edit interfaces interface rl0 vif rl0]
user@hostname# show
address 192.150.187.108 {
prefix-length: 24
broadcast: 192.150.187.255
}
> address 10.0.0.1 {
> prefix-length: 16
> broadcast: 10.0.255.255
> }
The delete command can be used to delete subtrees from the configuration. The deletion will be visible in the results of the show command, but will not actually take place until the changes are committed. The “-” indicates parts of the configuration that has been deleted but not yet been committed.
user@hostname# show interfaces interface rl0 vif rl0
address 192.150.187.108 {
prefix-length: 24
broadcast: 192.150.187.255
}
address 10.0.0.1 {
prefix-length: 16
broadcast: 10.0.255.255
}
[edit]
user@hostname# delete interfaces interface rl0 vif rl0 address 10.0.0.1
Deleting:
address 10.0.0.1 {
prefix-length: 16
broadcast: 10.0.255.255
}
OK
[edit]
user@hostname# show interfaces interface rl0 vif rl0
address 192.150.187.108 {
prefix-length: 24
broadcast: 192.150.187.255
}
- address 10.0.0.1 {
- prefix-length: 16
- broadcast: 10.0.255.255
- }
[edit interfaces interface rl0] user@hostname# commit OK
The commit command commits all the current configuration changes. This can take a number of seconds
before the response is given.
If xorpsh was built with debugging enabled, the response can be considerably more verbose than shown
above!
If two or more users are logged in using configuration mode, and one of them changes the configuration, the
others will receive a warning:
[edit] user@hostname# The configuration had been changed by user mjh user@hostname#
The user can discard a batch of changes by editing them back to their original configuration, or by using the exit command to leave configuration mode:
[edit] user@hostname# exit ERROR: There are uncommitted changes Use "commit" to commit the changes, or "exit discard" to discard them user@hostname# exit discard user@hostname>
Currently there is very limited support for configuring the xorpsh behavior. In the future there will be a more advanced configuration mechanism with a richer set of configuration options.
The default operational and configuration mode prompts are user@hostname> and user@hostname#
respectively.
The operational and configuration mode prompts can be modified by the following environmental variables respectively: XORP PROMPT OPERATIONAL and XORP PROMPT CONFIGURATION. For example:
user@hostname[10] env XORP_PROMPT_OPERATIONAL="foo "
XORP_PROMPT_CONFIGURATION="bar " ./xorpsh
Welcome to XORP on hostname
foo configure
Entering configuration mode.
There are no other users in configuration mode.
[edit]
bar
Typically xorpsh would be used as an interactive command shell. However, it is possible to use xorpsh
in non-interactive mode (e.g., as part of a shell script). This could be useful for automated XORP router
configuration such as adding new network interfaces to the XORP configuration for new PPP dial-up clients.
The following non-interactive modes are supported. Note that the xorpsh binary has to be in the execution path. Alternatively, xorpsh should be replaced with /path/to/xorpsh.
echo "show host os" | xorpsh cat filename | xorpsh xorpsh < filename
#!/bin/sh xorpsh <<! show host os !
xorpsh -c "show host os"
The “-c” option can be used more than once to execute multiple commands.
#!/usr/bin/env python
import time
import sys
import pexpect
child=pexpect.spawn ('xorpsh')
child.expect('user@hostname> ')
child.sendline('show host os | no-more')
child.sendeof()
while 1:
line = child.readline()
if not line:
break
print line,
child.close()
Note that if xorpsh is run in non-interactive more as part of an “expect” script where there is a TTY associated with the xorpsh process, then xorpsh may use the internal pager if the output from a command is very long. In that case, it is advisable that the internal pager is explicitly disabled by using the “no-more” pipe as in the above example.