cli_intro.tex

xorp源码hg

\>\>\>\>disable: false\\
\>\>\>\}\\
\>\>\>disable: false\\
\>\>\}\\
\>\>disable: false\\
\>\>discard: false\\
\>\}\\
\>targetname: "fea"\\
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}


\newpage
\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]\\
user@hostname\# \textbf{edit interfaces interface rl0 vif rl0}\\
\noindent[edit interfaces interface rl0 vif rl0]\\
user@hostname\# \textbf{show}\\
\>address 192.150.187.108 \{\\
\>\>prefix-length: 25\\
\>\>broadcast: 192.150.187.255\\
\>\}\\
\\
\noindent[edit interfaces interface rl0 vif rl0]\\
user@hostname\# \textbf{up}\\
\noindent[edit interfaces interface rl0]\\
user@hostname\# \textbf{top}\\
\noindent[edit]\\
user@hostname\#
\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}

The $<$\textit{filename}$>$ argument may be a path to a disk file,
or an Uniform Resource Identifier (URI) with a scheme of \emph{file},
\emph{ftp}, \emph{http}, or \emph{tftp}.
The \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 \emph{rtrmgr} block to point to these commands.
Commands are invoked with the following arguments:
\begin{itemize}
\item Any options specified in the \emph{args} variable for the command,
(\eg \emph{save-tftp-command-args}).
\item The full path name of a temporary file where the running XORP
configuration has been saved.
\item The URI specified to the \emph{save} command in the \xorpsh.
\end{itemize}
Note that currently no commands or scripts to perform these operations
are shipped with XORP.

For example:
\vspace{0.1in}

\noindent\framebox[\textwidth][l]{
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
\>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"\\
\>\}\\
\end{tabbing}
\end{alltt}
\end{minipage}
}

Then, if the user uses \xorpsh command
\textbf{load \textit{tftp://hostname/path/to/config.boot}}
to load the configuration, internally the \rtrmgr will use the following
command:

\textbf{/usr/local/sbin/xorp-tftp-get.sh -o $<$\textit{tmp-filename}$>$
\textit{tftp://hostname/path/to/config.boot}}

This command will download the configuration file to a temporary file (chosen
internally by the \rtrmgr) on the local filesystem and then the \rtrmgr will
load the configuration from that temporary file before deleting it.

Similarly, if the user uses \xorpsh command
\textbf{save \textit{tftp://hostname/path/to/config.boot}}
to save the configuration, internally the \rtrmgr will use the following
command:

\textbf{/usr/local/sbin/xorp-tftp-put.sh -i $<$\textit{tmp-filename}$>$
\textit{tftp://hostname/path/to/config.boot}}

First, the \rtrmgr will save the configuration to a temporary file (chosen
internally by the \rtrmgr) on the local filesystem. Then the
\textbf{/usr/local/sbin/xorp-tftp-put.sh} command will be used to upload that
file. Finally, the \rtrmgr will delete the temporary file.

\newpage
\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 can be 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 has been added
or modified 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]\\
user@hostname\# \textbf{show}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
\>\>\>prefix-length: 25\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\}\\
\>\}\\
\\
\noindent[edit interfaces interface rl0]\\
user@hostname\# \textbf{set vif rl0 address 192.150.187.108 prefix-length 24}\\
OK\\
\\
\noindent[edit interfaces interface rl0]\\
user@hostname\# \textbf{show}\\
\>description: "control interface"\\
\>vif rl0 \{\\
\>\>address 192.150.187.108 \{\\
>\>\>\>prefix-length: 24\\
\>\>\>broadcast: 192.150.187.255\\
\>\>\}\\
\>\}\\
\end{tabbing}
\end{alltt}
\end{minipage}
}

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

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

\end{itemize}

New configuration can be added by the \emph{set} command.~\footnote{Note that
prior to the XORP Release-1.3, the \textbf{create} command was used instead to
add new configuration nodes.}
If we type \emph{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
\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.

\newpage
For example, to configure a second address on interface/vif 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 vif rl0]\\
user@hostname\# \textbf{show}\\
\>address 192.150.187.108 \{\\
\>\>prefix-length: 24\\
\>\>broadcast: 192.150.187.255\\
\>\}\\
\\
\noindent[edit interfaces interface rl0 vif rl0]\\
user@hostname\# \textbf{set address 10.0.0.1 \{}\\
\>>\>\> \textbf{prefix-length 16}\\
\>>\>\> \textbf{broadcast 10.0.255.255}\\
\>>\>\> \textbf{\}}\\
\noindent[edit interfaces interface rl0 vif rl0]\\
user@hostname\# \textbf{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\\
>\>\}\\
\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. The ``{\tt -}'' indicates parts of the configuration that has
been deleted 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
user@hostname\# \textbf{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\\
\>\}\\
\\
\noindent[edit]\\
user@hostname\# \textbf{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\\
\noindent[edit]\\
user@hostname\# \textbf{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\\
-\>\}\\
\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]\\
user@hostname\# \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]\\
user@hostname\# \\
The configuration had been changed by user mjh\\
user@hostname\#
\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]\\
user@hostname\# \textbf{exit}\\
ERROR: There are uncommitted changes\\
Use "commit" to commit the changes, or "exit discard" to discard them\\
user@hostname\# \textbf{exit discard}\\
user@hostname>
\end{tabbing}
\end{alltt}
\end{minipage}
}
\vspace{0.1in}

\section{Configuring xorpsh Behavior}
\label{xorpsh: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.

\subsection{Configuring the xorpsh Prompt}

The default operational and configuration mode prompts are
\verb=user@hostname>= and \verb=user@hostname#= respectively.

The operational and configuration mode prompts can be modified by the
following environmental variables respectively:
{\textbf XORP\_PROMPT\_OPERATIONAL} and
{\textbf XORP\_PROMPT\_CONFIGURATION}. For example:

\begin{verbatim}
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 
\end{verbatim}

\section{Running xorpsh in Non-Interactive Mode}
\label{xorpsh:non-interactive-mode}

Typically \xorpsh would be used as an interactive command shell.
However, it is possible to use \xorpsh in non-interactive mode
(\eg 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 {\it xorpsh} binary has to be in the execution path.
Alternatively, {\it xorpsh} should be replaced with
{\it /path/to/xorpsh}.

\begin{itemize}

  \item Running \xorpsh as part of UNIX command-line pipes:

\begin{verbatim}
echo "show host os" | xorpsh
cat filename | xorpsh
xorpsh < filename
\end{verbatim}

  \item Running \xorpsh as part of a shell script:

\begin{verbatim}
#!/bin/sh

xorpsh <<!
show host os
!
\end{verbatim}

  \item Running commands that are supplied by the ``-c'' \xorpsh
   command-line option:

\begin{verbatim}
xorpsh -c "show host os"
\end{verbatim}

  \item Running \xorpsh as part of an ``expect'' script:

\begin{verbatim}
#!/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()
\end{verbatim}

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.

\end{itemize}