User Tools

Site Tools


latex2wiki:user_manual:command_structure

Command Structure

Introduction

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.

Running xorpsh

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.

Basic Commands

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

Command History and Command Line Editing

xorpsh supports emacs-style command history and editing of the text on the command line. The most important commands are:

  • The up-arrow or control-p moves to the previous command in the history.
  • The down-arrow or control-n moves to the next command in the history.
  • The left-arrow or control-b moves back along the command line.
  • The right-arrow or control-f move forward along the command line.
  • control-a moves to the beginning of the command line.
  • control-e moves to the end of the command line.
  • control-d deletes the character directly under the cursor.
  • control-t toggles (swaps) the character under the cursor with the character immediately preceding it.
  • control-space marks the current cursor position.
  • control-w deletes the text between the mark and the current cursor position, copying the deleted text to the cut buffer.
  • control-k kills (deletes) from the cursor to the end of the command line, copying the deleted text to the cut buffer.
  • control-y yanks (pastes) the text from the cut buffer, inserting it at the current cursor location.

Command Output Displaying

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)

Command Output Filtering

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)

Command Modes

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.

An user can only enter configuration mode if that user is in the xorp Unix group.

Operational Mode

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.

Show Command

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

Configuration Mode

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"

Moving around the Configuration Tree

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#

Loading and Saving Configurations

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:

  • Any options specified in the args variable for the command, (e.g., save-tftp-command-args).
  • The full path name of a temporary file where the running XORP configuration has been saved.
  • The URI specified to the save command in the xorpsh.

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.

Setting Configuration Values

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
    }
  }

Adding New Configuration

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
> }

Deleting Parts of the Configuration

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
- }

Committing Changes

[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#

Discarding Changes

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>

Configuring xorpsh Behavior

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.

Configuring the xorpsh Prompt

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 

Running xorpsh in Non-Interactive Mode

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.

  • Running xorpsh as part of UNIX command-line pipes:
     
    echo "show host os" | xorpsh
    cat filename | xorpsh
    xorpsh < filename 
  • Running xorpsh as part of a shell script:
    #!/bin/sh
    xorpsh <<!
    show host os
    !
  • Running commands that are supplied by the “-c” xorpsh command-line option:
    xorpsh -c "show host os"

    The “-c” option can be used more than once to execute multiple commands.

  • Running xorpsh as part of an “expect” script:
    #!/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.

1) Note that prior to the XORP Release-1.3, the create command was used instead to add new configuration nodes.
latex2wiki/user_manual/command_structure.txt · Last modified: 2011/03/09 23:15 by Pierre Lepropre