%
% $XORP: xorp/docs/rtrmgr/xorpsh_userguide.tex,v 1.13 2004/07/09 04:42:54 pavlin Exp $
%

\documentclass[11pt]{article}

%\usepackage[dvips]{changebar}

\usepackage{subfigure}
\usepackage{fullpage}
\usepackage{setspace}
\usepackage{times}
\usepackage{latexsym}
\usepackage{psfig}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{color}
\usepackage{amsmath}
\usepackage{alltt}
\usepackage{stmaryrd}
%\usepackage[dvipdf]{graphics}
%\usepackage[dvips]{graphicx}
%\usepackage{xorp}

\definecolor{gray}{rgb}{0.5,0.5,0.5}
\newcommand{\etc}{\emph{etc.}\xspace}
\newcommand{\ie}{\emph{i.e.,}\xspace}
\newcommand{\eg}{\emph{e.g.,}\xspace}
%\newcommand{\comment}[1]{{\color{gray}[\textsf{#1}]}}
\newcommand{\comment}[1]{}

% Changebar stuff
% \newenvironment{colorcode}{\color{blue}}{}
% \renewcommand{\cbstart}{\begin{colorcode}}
% \renewcommand{\cbend}{\end{colorcode}}

%\newcommand{\xorpsh}{\textsc{xorpsh}}
\newcommand{\xorpsh}{{\sf\small xorpsh}\xspace}

\title{XORP Command Line Interface User Guide\\
Part 1: Command Structure \\
\vspace{1ex}
Version 1.0}
\author{ XORP Project					\\
	 International Computer Science Institute	\\
	 Berkeley, CA 94704, USA			\\
	 {\it feedback@xorp.org}
}
\date{July 8, 2004}

%\twocolumn
\begin{document}
\maketitle

\section{Introduction}
To interact with a XORP router using the command line interface (CLI),
a user runs \xorpsh.  This allows configuration of the router and
monitoring of the router state.  

In this document we describe how to interact with \xorpsh.  This
document does not provide specifics of how to configure BGP, PIM, SNMP
and other processes - this will eventually be described in additional
documents.

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.

\section{Running xorpsh}
\xorpsh 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, it is envisaged that \xorpsh might be set up as a 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
rtrmgr process, 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 the user is to be
permitted to make changes to the running router configuration, they
need to be in the Unix group {\tt xorp}.  The choice of GID for group
xorp is not important.

\xorpsh needs to be able to communicate with the rtrmgr using the local
file system.  If the rtrmgr cannot write files in /tmp that \xorpsh
can read, then \xorpsh will not be able to authenticate the user to the
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.

\section{Basic Commands}

On starting \xorpsh, you will be presented with a command line prompt:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{\textwidth}
\begin{alltt}
Xorp>
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\noindent
You can exit \xorpsh at any time by trying Control-d.

\noindent
Typing ``?'' at the prompt will list the commands currently available to
you:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}[l]{\textwidth}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{?}\\
Po\=ssible compl\=etions:\\
\>configure       \>Switch to configuration mode\\
\>help            \>Provide help with commands\\
\>quit            \>Quit this command session\\
\>show            \>Display information about the system
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\noindent
If you type the first letter or letters of a command, and hit
{\tt <Tab>}, then command completion will occur.

\noindent
At any time you can type ``?'' again to see further 
command completions.  For
example:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{\textwidth}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{config?}\\
Po\=ssible compl\=etions:\\
\>configure\>Switch to configuration mode\\
Xorp> \textbf{config}
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\noindent
If the cursor is after the command, typing ``?'' will list the possible
parameters for the command:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{4in}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{configure ?}\\
Po\=ssible compl\=etions:\\
\><[Enter]>       \>Execute this command\\
\>exclusive       \>Switch to configuration mode, locking out other users\\
Xorp> \textbf{configure}
\end{tabbing}
\end{alltt}
\end{minipage}
}

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

\newpage
\section{Command Modes}

\xorpsh has two command modes:
\begin{description}
\item{\bf Operational Mode,}  which allows interaction with the router
to monitor it's operation and status.
\item{\bf Configuration Mode,} which allows the user to view the
configuration of the router, to change that configuration, and to
load and save configurations to file.
\end{description}
Generally speaking, operational mode is considered to give
non-privileged access; there should be nothing a 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 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.

A user can only enter configuration mode if they are in the {\tt xorp} Unix
group.

\newpage
\section{Operational Mode}
\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{?}\\
Po\=ssible compl\=etions:\\
\>configure       \>Switch to configuration mode\\
\>help            \>Provide help with commands\\
\>quit            \>Quit this command session\\
\>show            \>Display information about the system
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

The main commands in operational mode are:
\begin{description}
\item{\bf configure}: switches from operational mode to configuration
mode.
\item{\bf help}: provides online help.
\item{\bf quit}: quit from xorpsh.
\item{\bf show}: displays many aspects of the running state of the
router.
\end{description}

\subsection{Show Command}
\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{show ?}\\
Po\=ssible compl\=etions:\\
\>  <[Enter]>       \>Execute this command\\
\>  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\\
Xorp> \textbf{show}
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\noindent
The \emph{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 {\tt show bgp} commands\footnote{Note that
currently all possible commands are shown, even if the router is not
running a particular protocol.}.

As an example, we show the peers of a BGP router:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{show bgp peers detail}\\
OK\\
Pe\=er 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\\
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\newpage
\section{Configuration Mode}
\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
Xorp> \textbf{configure}\\
Entering configuration mode.\\
There are no other users in configuration mode.\\
\\
\noindent[edit]\\
XORP>
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\noindent
When in configuration mode, the command prompt changes to be all
capitals.
The command prompt is also usually preceded by a line indicating which
part of the configuration tree is currently being edited.
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
[edit]\\
XORP> \textbf{?}\\
Po\=ssible completi\=ons:\\
\>  create          \>Create a sub-element\\
\>  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\\
\>  show            \>Show the value of a parameter\\
\>  top             \>Exit to top level of configuration\\
\>  up              \>Exit one level of configuration\\
XORP> 
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\noindent
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 \emph{show} command:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
[edit]\\
XORP> \textbf{show interfaces}\\
\>interface rl0 \{\\
\>\>description: "control interface"\\
\>\>vif rl0 \{\\
\>\>\>address 192.150.187.108 \{\\
\>\>\>\>prefix-length: 25\\
\>\>\>\>broadcast: 192.150.187.255\\
\>\>\>\>enabled: true\\
\>\>\>\}\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\>targetname: "fea"\\
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\subsection{Moving around the Configuration Tree}
You can change the current location in the configuration tree using
the \emph{edit}, \emph{exit}, \emph{quit}, \emph{top} and \emph{up} commands.
\begin{itemize}
\item \textbf{edit $<$\textit{element name}$>$}:       Edit a sub-element
\item \textbf{exit}:       Exit from this configuration level, or if
at top level, exit configuration mode.
\item \textbf{quit}:       Quit from this level
\item \textbf{top}:        Exit to top level of configuration
\item \textbf{up}:         Exit one level of configuration
\end{itemize}

\noindent
For example:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
[edit]\\
XORP> \textbf{edit interfaces interface rl0 vif rl0}\\
\\
\noindent[edit interfaces interface rl0 vif rl0]\\
XORP> \textbf{show}\\
\>address 192.150.187.108 \{\\
\>\>prefix-length: 25\\
\>\>broadcast: 192.150.187.255\\
\>\>enabled: true\\
\>\}\\
\>enabled: true\\
\\
\noindent[edit interfaces interface rl0 vif rl0]\\
XORP> \textbf{up}\\
\\
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{top}\\
\\
\noindent[edit]\\
XORP>
\end{tabbing}
\end{alltt}
\end{minipage}
}

\subsection{Loading and Saving Configurations}

On startup, the 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:
\begin{itemize}
\item \textbf{save $<$\textit{filename}$>$}: save the current
configuration in the specified file.
\item \textbf{load $<$\textit{filename}$>$}: load the specified file,
discarding the currently running configuration.
\end{itemize}

\subsection{Setting Configuration Values}

\begin{itemize}
\item \textbf{set $<$\textit{path to config}$>$
$<$\textit{value}$>$}: set the value of the specified configuration
node.
\end{itemize}
The \emph{set} command is used to set or change the value of a configuration
option.  The change does not actually take effect immediately - the
\emph{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
``{\tt >}'' indicates parts of the configuration that have changed but
not yet been committed.
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{show}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
\>\>\>prefix-length: 25\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\>enabled: true\\
\\
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{set vif rl0 address 192.150.187.108 prefix-length 24}\\
OK\\
\\
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{show}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
>\>\>\>prefix-length: 24\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\end{tabbing}
\end{alltt}
\end{minipage}
}

\newpage
\subsection{Adding New Configuration}
\begin{itemize}

\item \textbf{create $<$\textit{path to new config node}$>$}
: create new configuration node.
\item \textbf{create $<$\textit{path to new config node}$>$ \{}
: create new configuration node and start editing it.

\end{itemize}

New configuration can be added by the \emph{create} command.
If we type \emph{create} 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
\emph{edit} command.
If we type \emph{\{} 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 vif on interface rl0:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{show}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
\>\>\>prefix-length: 24\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\>enabled: true\\
\\
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{create vif rl0b \{}\\
\>\>>\> \textbf{address 10.0.0.1 \{}\\
\>\>>\>\> \textbf{prefix-length 16}\\
\>\>>\>\> \textbf{broadcast 10.0.255.255}\\
\>\>>\>\> \textbf{enabled true}\\
\>\>>\>\> \textbf{\}}\\
\>\>>\>\> \textbf{enabled true}\\
\>\>>\> \textbf{\}}\\
OK. Use "commit" to apply these changes.\\
\\
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{show}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
\>\>\>prefix-length: 24\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
> vif rl0b \{\\
>\>\> address 10.0.0.1 \{\\
>\>\>\> prefix-length: 16\\
>\>\>\> broadcast: 10.0.255.255\\
>\>\>\> enabled: true\\
>\>\>\}\\
>\>\>enabled: true\\
>\>\}\\
\>enabled: true\\
\end{tabbing}
\end{alltt}
\end{minipage}
}

\subsection{Deleting Parts of the Configuration}

The \emph{delete} command can be used to delete subtrees from the
configuration.  The deletion will be visible in the results of the
\emph{show} command, but will not actually take place until the changes are
committed.
\vspace{0.1in}


\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
XORP> \textbf{show interfaces interface rl0}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
\>\>\>prefix-length: 24\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\>vif rl0b \{\\
\>\> address 10.0.0.1 \{\\
\>\>\> prefix-length: 16\\
\>\>\> broadcast: 10.0.255.255\\
\>\>\> enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\>enabled: true\\
\\
\noindent[edit]\\
XORP> \textbf{delete interfaces interface rl0 vif rl0b}\\
Deleting:\\
\>address 10.0.0.1 \{\\
\>\>prefix-length: 16\\
\>\>broadcast: 10.0.255.255\\
\>\>enabled: true\\
\>\}\\
\\
OK\\
\\
\noindent[edit]\\
XORP> \textbf{show interfaces interface rl0}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
\>\>\>prefix-length: 24\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\>enabled: true\\
\>\>\}\\
\>\>enabled: true\\
\>\}\\
\>enabled: true
\end{tabbing}
\end{alltt}
\end{minipage}
}

\newpage
\subsection{Committing Changes}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
\noindent[edit interfaces interface rl0]\\
XORP> \textbf{commit}\\
OK
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

The \emph{commit} command commits all the current configuration changes.
This can take a number of seconds before the response is given.

{\it 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:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
\noindent[edit]\\
XORP>\\
The configuration had been changed by user mjh\\
XORP>
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}


\subsection{Discarding Changes}

The user can discard a batch of changes by editing them back to their
original configuration, or by using the \emph{exit} command to leave
configuration mode:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
\noindent[edit]\\
XORP> \textbf{exit}\\
ERROR: There are uncommitted changes\\
Use "commit" to commit the changes, or "exit discard" to discard them\\
\\
XORP> \textbf{exit discard}\\
Xorp>
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}


\end{document}


