% % $XORP: xorp/docs/user_manual/cli_intro.tex,v 1.20 2007/11/29 01:52:35 pavlin Exp $ % \chapter{Command Structure} \label{xorpsh} \section{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. \section{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 {\tt xorp}. The choice of GID for group {\tt xorp} is not important. \xorpsh needs to be able to communicate with the \xorp router management process \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. To facilitate automated \xorp router configuration, it is possible to use \xorpsh in non-interactive mode (\eg as part of a shell script). This is described in details in Section~\ref{xorpsh:non-interactive-mode}. \newpage \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} user@hostname> \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} user@hostname> \textbf{?}\\ Po\=ssible 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 \end{tabbing} \end{alltt} \end{minipage} } \vspace{0.1in} \noindent If you type the first letter or letters of a command, and hit {\tt }, 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} user@hostname> \textbf{config?}\\ Po\=ssible completions: \=\\ \>configure\>Switch to configuration mode\\ user@hostname> \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} user@hostname> \textbf{configure ?}\\ Po\=ssible completions: \=\\ \><[Enter]> \>Execute this command\\ \>exclusive \>Switch to configuration mode, locking out other users\\ user@hostname> \textbf{configure} \end{tabbing} \end{alltt} \end{minipage} } \newpage \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 \subsection{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 {\bf more}-like interface to display it one screen at a time. In that case the bottom of the display shows a {\bf --More--} prompt. If the screen displays the end of the output, the prompt is {\bf --More-- (END)}. Typing 'h' at the {\bf --More--} prompt can be used to display help information about available commands: \begin{verbatim} 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) \end{verbatim} \newpage \subsection{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 '$\mid$' as one of the options: \vspace{0.1in} \noindent\framebox[\textwidth][l]{ \begin{minipage}[l]{\textwidth} \begin{alltt} \begin{tabbing} user@hostname> \textbf{show host date | ?}\\ Po\=ssible 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) \end{tabbing} \end{alltt} \end{minipage} } \vspace{0.1in} %% %% TODO: add detailed description for each pipe command %% \newpage \section{Command Modes} \xorpsh has two command modes: \begin{description} \item{\bf Operational Mode,} which allows interaction with the router to monitor its 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 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 \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 {\tt xorp} Unix group. \section{Operational Mode} \noindent\framebox[\textwidth][l]{ \begin{minipage}{6in} \begin{alltt} \begin{tabbing} user@hostname> \textbf{?}\\ Po\=ssible 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 \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 exit}: exit from \xorpsh. \item{\bf help}: provides online help. \item{\bf quit}: quit from \xorpsh. It is equivalent to the {\bf exit} command. \item{\bf show}: displays many aspects of the running state of the router. \end{description} \newpage \subsection{Show Command} \noindent\framebox[\textwidth][l]{ \begin{minipage}{6in} \begin{alltt} \begin{tabbing} user@hostname> \textbf{show ?}\\ Po\=ssible 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\\ user@hostname> \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. 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} user@hostname> \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} user@hostname> \textbf{configure}\\ Entering configuration mode.\\ There are no other users in configuration mode.\\ \noindent[edit]\\ user@hostname\# \end{tabbing} \end{alltt} \end{minipage} } \vspace{0.1in} \noindent When in configuration mode, the command prompt changes from \verb=user@hostname>= to \verb=user@hostname#=. 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]\\ user@hostname\# \textbf{?}\\ Po\=ssible 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\# \end{tabbing} \end{alltt} \end{minipage} } \vspace{0.1in} \newpage \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]\\ user@hostname\# \textbf{show interfaces}\\ \>interface rl0 \{\\ \>\>description: "control interface"\\ \>\>vif rl0 \{\\ \>\>\>address 192.150.187.108 \{\\ \>\>\>\>prefix-length: 25\\ \>\>\>\>broadcast: 192.150.187.255\\ \>\>\>\}\\ \>\>\}\\ \>\}\\ \end{tabbing} \end{alltt} \end{minipage} } \vspace{0.1in} Note that the \emph{show} command suppresses parameters that have default values (as specified in the corresponding router manager template files). Use command \emph{show -all} to show the complete configuration including the parameters with default values: \noindent\framebox[\textwidth][l]{ \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xx\=xx\=xx\=xx\=xx\=\kill [edit]\\ user@hostname\# \textbf{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"\\ \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 < ') 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}