%
% $XORP: xorp/docs/rtrmgr/rtrmgr.tex,v 1.52 2006/08/02 05:43:35 pavlin Exp $
%

\documentclass[11pt]{article}

%\usepackage[dvips]{changebar}

\usepackage{subfigure}
\usepackage{fullpage}
\usepackage{setspace}
\usepackage{times}
\usepackage{latexsym}
\usepackage{epsfig}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{color}
\usepackage{amsmath}
\usepackage{rotating}
\usepackage{moreverb}
\usepackage{listings}
\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}}

% \pagestyle{empty}

\begin{document}

\title{XORP Router Manager Process (rtrmgr) \\
\vspace{1ex}
Version 1.3}
\author{ XORP Project					\\
	 International Computer Science Institute	\\
	 Berkeley, CA 94704, USA			\\
         {\it http://www.xorp.org/}			\\
	 {\it feedback@xorp.org}
}
\date{August 2, 2006}

\maketitle


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

This document provides a high-level technical overview of the Router
Manager (rtrmgr) code structure, intended to aid anyone needing to
understand or modify the software.   It is not a user manual.

The XORP software base consists of a number of routing protocols (BGP,
OSPF, PIM-SM, etc), a Routing Information Base (RIB) process, a
Forwarding Engine Abstraction (FEA) process, and a forwarding path.
Other management, monitoring or application processes may also
supplement this set.  Figure \ref{overview} illustrates these
processes and their principle communication channels.

\begin{figure}[htb]
\centerline{\includegraphics[width=0.6\textwidth]{figs/processes3}}
\vspace{.05in}
\caption{\label{overview}Overview of XORP processes}
\end{figure}

For research purposes, these processes may be started manually or from
scripts, so long as the dependencies between then are satisfied.  But
when using XORP in a more operational environment, the network manager
typically does not wish to see the software structure, but rather
would like to interact with the router {\it as a whole}.  Minimally, this
consists of a configuration file for router startup, and a command
line interface to interact with the router during operation.  The
rtrmgr process provides this unified view of the router.

The rtrmgr is normally the only process explicitly started at router
startup.  The rtrmgr process includes a built-in XRL finder, so no
external finder process is required.  The following sequence of
actions then occurs:

\begin{enumerate}

  \item The rtrmgr reads all the template files in the router's template
  directory.  Typically there is one template file per XORP process that
  might be needed.  A template file describes the functionality that is
  provided by the corresponding process in terms of all of the
  configuration parameters that may be set.  It also describes the
  dependencies that need to be satisfied before the process can be
  started.  After reading the template files, the rtrmgr knows all the
  configuration parameters currently supportable on this router, and it
  stores this information in its \textit{template tree}.
  After all template files are read, the template tree is checked for
  errors (\eg invalid variable names, etc). The rtrmgr will exit
  if there is an error.

  \item The rtrmgr next reads the contents of the XRL directory to discover
  all the XRLs that are supported by the processes on this router.
  These XRLs are then checked against the XRLs in the template tree.  As
  it is normal for the XRLs in the XRL directory to be used to generate
  stub code in the XORP processes, this forms the definitive version of
  a particular XRL.  Checking against this version detects if a template
  file has somehow become out of sync with the router's codebase.  Doing
  this check at startup prevents subtle run time errors later.  The
  rtrmgr will exit if a mismatch is discovered.

  \item The rtrmgr then reads the router configuration file.  All the
  configuration options in the config file must correspond to
  configurable functionality as described by the template files.  As it
  reads the config file, the rtrmgr stores the intended configuration in
  its \textit{configuration tree}.  At this point, the nodes in the
  configuration tree are annotated as \textit{not existing} - that is
  this part of the configuration has not yet been communicated to the
  process that will implement the functionality.

  \item The rtrmgr next traverses the configuration tree to discover the list
  of processes that need to be started to provide the required
  functionality.  Typically not all the available software on the router
  will be needed for a specific configuration.

  \item The rtrmgr traverses the template tree again to discover an order for
  starting the required processes that satisfies all their dependencies.

  \item The rtrmgr starts the first process in the list of processes to be
  started.

  \item If no error occurs, the rtrmgr traverses the configuration tree to
  build the list of commands that need to be executed to configure the process
  just started.  A command can be either an XRL or an external program.
  These commands are then called, one after another, with the
  successful completion of one command triggering the calling of the next.
  The commands are ordered according to the command semantics
  (\eg see below the description of commands
  \%create, \%activate, etc). If the semantics of the commands
  do not specify the ordering, then the commands follow the order they
  are defined in the rtrmgr template files.
  Some processes may require calling a transaction start command before
  configuration, and a transaction complete command after configuration -
  the rtrmgr can do this if required.

  \item If no error occurred during configuration, the next process is started,
  and configured, and so forth, until all the required processes are
  started and configured.

  \item At this point, the router is up and running.  The rtrmgr will now
  allow connections from the xorpsh process to allow interactive
  operation.

\end{enumerate}

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Template Files}

The router manager reads a directory of template files to discover the
configuration options that the router supports.  A fragment of such a
configuration file might look like:

\begin{verbatim}
protocols {
  ospf {
    router-id: ipv4;
    mospf: toggle = false;
    flood_rate: i32;
    area @: ipv4 {
      stub: toggle = false;
      interface @: txt {
        disable: toggle = false;
        hello-interval: u32 = 30;
        dead-interval: u32 = 95;
      }
    }
  }
}
\end{verbatim}

This defines a subset of the configuration options for OSPF.  The
configuration options form a tree, with three types of nodes:

\begin{itemize}

  \item Structural nodes such as {\tt protocol} and {\tt ospf} that exist
  merely to provide scope.

  \item Named interior nodes such as ``{\tt area @}'' and
  ``{\tt interface @}'', where there can be multiple instances of the node.
  Symbol {\tt @} indicates that a name is required; in the case of ``area @''
  the fragment above specifies that the name must be an IPv4 address.

  \item Leaf nodes such as  {\tt flood\_rate} and
  {\tt hello-interval}.  These nodes are also typed, and may optionally
  specify a default value.  In the example above, {\tt hello-interval} is
  of type {\tt u32} (unsigned 32 bit integer), and takes the default value of
  30.

\end{itemize}

Thus the template tree created from this template file would look like:

\begin{figure}[htb]
\centerline{\includegraphics[width=0.7\textwidth]{figs/template}}
\vspace{.05in}
%\caption{\label{overview}Overview of XORP processes}
\end{figure}

The same node may occur multiple times in the template file.  This
might happen because the node can take more than one type (for
example, it might have an IPv4 or an IPv6 address), or it might happen
because the second definition adds information to the existing
definition.

In addition to specifying the configurable options, the template file
should also specify what the rtrmgr should do when an option is
modified.  These commands annotating the template file begin with a
``{\tt \%}''.  Thus the template file above might also contain the
following annotated version of the template tree:

\begin{verbatim}
protocols ospf {
  %modinfo: provides ospf;
  %modinfo: depends rib;
  %modinfo: path "ospfd/xorp/ospfd";
  %modinfo: default_targetname "ospf";
  %mandatory: $(@.targetname), $(@.router-id);
  targetname {
    %set:;
  }
  router-id {
    %set: xrl "$(ospf.targetname)/ospf/0.1/set_router_id?id:u32=$(@)";
    %get: xrl "$(ospf.targetname)/ospf/0.1/get_router_id->id:u32";
  }
  area @ {
    %create: xrl "$(ospf.targetname)/ospf/0.1/add_or_configure_area?area_id:u32=$(area.@)&is_stub:bool=$(@.stub)";
    %delete: xrl "$(ospf.targetname)/ospf/0.1/delete_area?area_id:u32=$(area.@)";
  }
  mospf {
    %set: xrl "$(ospf.targetname)/ospf/0.1/set_mospf?enabled:bool=$(@)";
    %delete: xrl "$(ospf.targetname)/ospf/0.1/set_mospf?enabled:bool=$(DEFAULT)";
    %get: xrl "$(ospf.targetname)/ospf/0.1/get_mospf->enabled:bool=$(@)";
  }
}
\end{verbatim}

The first four annotations apply to the ``protocols ospf'' node, and
specify the ``\%modinfo'' command, which provides information about
the module providing this functionality.  In this case they specify
the following:

\begin{itemize}

  \item This functionality is provided by the module called {\tt ospf}.

  \item This module depends on the module called {\tt rib}.

  \item The program in {\tt ospfd/xorp/ospfd} should be run run to
  provide this module.

  \item XRL target name {\tt ospf} should be used by default when validating
  an XRL specification that uses a variable inside the {\tt ospf} module
  (\eg {\tt \$(ospf.targetname)}) to specify the XRL target.

\end{itemize}

The ``\%mandatory'' annotation contains the list of nodes or variables
that must be configured in the user configuration file or that must
have a default value. In the above example, this applies to variables
``{\tt targetname}'' and ``{\tt router-id}''.

The ``{\tt protocols ospf targetname}'' node carries an annotation to
specify the existence of variable name ``{\tt targetname}'' that
can be used to specify the XRL target name of an OSPF instance.
The specific value of ``{\tt targetname}'' can be configured elsewhere.

The ``{\tt protocols ospf router-id}'' node carries annotations to set
the value of the router ID in the ospf process, and to get the value
back.  The set command is:

\begin{verbatim}
    %set: xrl "$(ospf.targetname)/ospf/0.1/set_router_id?id:u32=$(@)";
\end{verbatim}

This specifies that to set this value, the rtrmgr must call the
specified XRL.  In this case it specifies a variable expansion of
variables {\tt \$(ospf.targetname)} and  {\tt \$(@)}.  All variables take the
form {\tt \$(}...{\tt )}.

The variable {\tt \$(ospf.targetname)} means the value of node
``{\tt protocols ospf targetname}''.
The variable {\tt \$(@)} means the value of the current node.
Hence, if the targetname is set in the configuration tree to (or had a default
value in the template tree of) {\tt "ospf"}, and the router ID node in the
configuration tree had the value 1.2.3.4, then the XRL to call would be:

\begin{verbatim}
    ospf/ospf/0.1/set_router_id?id:u32=1.2.3.4
\end{verbatim}

The {\tt \%set} command only applies to leaf nodes that have values and only
if the value is allowed to be changed.
For example, node ``{\tt protocols ospf router-id}'' has {\tt \%set} command
because its value can be changed.
On contrary, node ``{\tt protocols ospf area @}'' does not have
{\tt \%set} command, because it defines a node that can have multiple
instances. Each instance has a value when the instance is created, but that
value cannot be changed later.

Internal nodes would typically use the {\tt \%create} command to
create a new instance of the node, as shown with the ``{\tt protocols ospf
area @}'' node.  In the example above, the {\tt \%create} command
involves two variable expansions: {\tt \$(area.@)} and {\tt
\$(@.stub)}.  The form {\tt \$(area.@)} means ``this area'', and so
in this case it is directly equivalent to {\tt \$(@)} meaning ``this node''.
The variable {\tt \$(@.stub)} means the value of the leaf node called
{\tt stub} that is a child node of ``this node''.

Default template value of a variable can be specified by the keyword
{\tt DEFAULT}. For example, {\tt \$(DEFAULT)} or {\tt \$(@.DEFAULT)}
would refer to the default template value of ``this'' node, while
{\tt \$(foo.bar.DEFAULT)} would refer to the default template value
of node {\tt "foo.bar"}.

Thus, the template tree specifies the following information:

\begin{itemize}

  \item The nodes of the tree specify all the configuration options
  possible on the router.

  \item Some of the nodes are annotated with information to indicate
  which software to run to provide the functionality rooted at that
  node, to indicate which other modules this software depends on
  being running, and to provide additional information about this module.

  \item Most of the nodes are annotated with commands to be run when the
  value of the node changes in the configuration tree, when a new
  instance of the node is created or an instance of the node is deleted
  in the configuration tree, or to get the current value of a node from
  the running processes providing the functionality.

\end{itemize}

Note that for verification purpuse all variable names must refer to valid
nodes in the template tree. Hence, the template tree may contain dummy nodes
that shoudn't be used for configuration purpose. For example, the internal
variable {\tt TID} that can be used to store the transient transaction ID
should be specified as:

\begin{verbatim}
interfaces {
  %modinfo: ...
  ...

  TID {
    %create:;
  }
  ...
}

\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Template Tree Node Types}

The following types are currently supported for template tree nodes:

\begin{description}

  \item{\tt u32}\\
  Unsigned 32 bit integer

  \item{\tt u32range}\\
  A range of unsigned 32 bit integers defined by an upper and lower
  inclusive boundary.  Boundaries are separated by two dots,
  e.g. {\tt 1234..5678}.  If upper and lower boundaries are equal it is
  sufficient to specify only a single value, e.g. {\tt 1234}.

  \item{\tt i32}\\
  Signed 32 bit integer

  \item{\tt bool}\\
  Boolean - valid values are {\tt true} and {\tt false}.

  \item{\tt toggle}\\
  Similar to boolean, but requires a default value.  Display of the
  config tree node is suppressed if the value is the default.

  \item{\tt ipv4}\\
  An IPv4 address in dotted decimal format.

  \item{\tt ipv4net}\\
  An IPv4 address and prefix length in the
  conventional format.  E.g.: {\tt 1.2.3.4/24}.

  \item{\tt ipv4range}\\
  A range of IPv4 addresses defined by an upper and lower inclusive boundary.
  IPv4 addresses are specified in dotted decimal format delimited by two dots,
  e.g. {\tt 1.2.3.4..5.6.7.8}. If upper and lower boundaries are equal it is
  sufficient to specify only a single value, e.g. {\tt 1.2.3.4}.

  \item{\tt ipv6}\\
  An IPv6 address in the canonical colon-separated human-readable format.

  \item{\tt ipv6net}\\
  An IPv6 address and prefix in the conventional format.
  E.g.: {\tt fe80::1/64}

  \item{\tt ipv6range}\\
  A range of IPv6 addresses defined by an upper and lower inclusive boundary.
  IPv6 addresses are specified in colon-separated format and are delimited
  by two dots, e.g. {\tt fe80::1234..fe80::5678}.
  If upper and lower boundaries are equal it is
  sufficient to specify only a single value, e.g. {\tt fe80::1234}.

  \item{\tt macaddr}\\
  An MAC address in the conventional colon-separated hex format.
  E.g.: {\tt 00:c0:4f:68:8c:58}

  \item{\tt com32}\\
  Unsigned 32 bit integer representing a BGP community tag.  It can be
  specified either in a colon-separated format using two 16 bit integers,
  e.g. {\tt 65001:1}, or as a single 32 bit unsigned integer.

\end{description}

It is likely that additional types will be added in the future, as
they are found to be needed.

\subsection{Template Tree Commands}
This section provides a complete listing of all the template tree
commands that the rtrmgr supports.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%modinfo} Command.}

The sub-commands to the {\tt \%modinfo} command are:

\begin{description}

  \item {{\tt \%modinfo: provides }{\it ModuleName}} \\
  The {\tt provides} subcommand takes one additional parameter, which gives the
  name of the module providing the functionality rooted at this node.

  \item {{\tt \%modinfo: depends }{\it list of modules}} \\
  The {\tt depends} subcommand takes at least one additional
  parameter, giving a list of the other modules that must
  be running and configured before this module may be started.

  \item {{\tt \%modinfo: path }{\it ProgramPath}} \\
  The {\tt path} subcommand takes one additional parameter giving the pathname
  of the software to be run
  to provide this functionality.  The pathname may be absolute or
  relative to the root of the XORP tree. The ordering in computing the root of
  the tree is: (a) the shell environment XORP\_ROOT (if exists); (b) the parent
  directory the rtrmgr is run from (only if it contains the
  etc/templates and the xrl/targets directories); (c) the XORP\_ROOT value as
  defined in config.h (currently this is the installation directory, and
  defaults to ``/usr/local/xorp'').

  \item {{\tt \%modinfo: default\_targetname }{\it TargetName}} \\
  The {\tt default\_targetname} subcommand takes one additional parameter
  giving the value of the XRL target name that should be used by default when
  validating an XRL specification (\eg if the specification uses a variable
  inside that module to specify the XRL target name).

  \item {{\tt \%modinfo: start\_commit }{\it method }{\it argument}} \\
  The {\tt start\_commit} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be call before performing any
  change to the configuration of the module. The only methods currently
  supported are {\tt xrl} which takes an XRL specification as an argument, and
  {\tt program} which takes an executable program as an argument.

  \item {{\tt \%modinfo: end\_commit }{\it method }{\it argument}} \\
  The {\tt end\_commit} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be called to complete any change
  to the configuration of the module. The only methods currently supported are
  {\tt xrl} which takes an XRL specification as an argument, and {\tt program}
  which takes an executable program as an argument.
  Both {\tt start\_commit} and {\tt end\_commit} are optional. They provide a
  way to make batch changes to a module configuration as an atomic operation.

  \item {{\tt \%modinfo: status\_method }{\it method }{\it argument}} \\
  The {\tt status\_method} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be used to discover the status of
  the module.
  The only methods current supported are {\tt xrl} which takes an XRL
  specification as an argument, and {\tt program} which takes an executable
  program as an argument.

  \item {{\tt \%modinfo: startup\_method }{\it method }{\it argument}} \\
  The {\tt startup\_method} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be used to gracefully startup the
  module. The only methods current supported are {\tt xrl} which takes an XRL
  specification as an argument, and {\tt program} which takes an executable
  program as an argument.

  Before the {\tt startup\_method} subcommand is called, it is expected
  that the process is in {\tt PROC\_STARTUP} state; after the subcommand
  is called the process should transition to the {\tt PROC\_READY} state.
  Note that this subcommand is optional and if it is not specified, then
  it is expected that the process will transition on its own to the
  {\tt PROC\_READY} state.

  \item {{\tt \%modinfo: shutdown\_method }{\it method }{\it argument}} \\
  The {\tt shutdown\_method} subcommand takes two or more additional
  parameters, that are used to specify the mechanism to be used to gracefully
  shutdown the module. The only methods current supported are {\tt xrl} which
  takes an XRL specification as an argument, and {\tt program} which takes an
  executable program as an argument.
  If the process does not then transition to {\tt PROC\_SHUTDOWN} state, the
  rtrmgr will then kill the process.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%mandatory} Command.}

{\tt \%mandatory} is used to specify the list of nodes or variables
that must be configured in the user configuration file or that must
have a default value. This command can appear multiple times anywhere in the
template tree. If it appears multiple times within the same template node,
then all listed nodes are mandatory. However, note that it cannot be used
to specify a multi-value node such as\\
{\tt \$(interfaces.interface.@.vif.@.address.@)}.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%create} Command.}

{\tt \%create} is used to create a new instance of an interior node in
the configuration tree.

\begin{itemize}

  \item The first parameter indicates the form of
  action to take to perform this action - typically it is {\tt xrl}
  which indicates an XRL should be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to create the new configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to create the new configuration tree instance of this
  template tree node. 

\end{itemize}

Note that if a node has no {\tt \%create} command, then the {\tt \%set}
command (if exists) for that node is used instead (see below).

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%activate} Command.}

{\tt \%activate} is used to activate a new instance of an interior
node in the configuration tree.  It is typically paired with {\tt
\%create} - the {\tt \%create} command is executed before the relevant
configuration of the node's children has been performed, whereas {\tt
\%activate} is executed after the node's children have been
configured.  A particular interior node might have either {\tt
\%create}, {\tt \%activate} or both.

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to activate the new configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to activate the new configuration tree instance of this
  template tree node.

\end{itemize}

For example, if the template tree held the following:

\begin{tabbing}
\tt addr\=\tt ess \=\tt@: ipv4 \{\\
    \>\tt\%create: xrl {\it XRL1};\\
    \>\tt\%activate: xrl {\it XRL2};\\
    \>\tt netmask: ipv4 \{\\
        \>\>\tt\%set: xrl {\it XRL3};\\
    \>\tt\}\\
\tt\}
\end{tabbing}

Then when an instance of address and netmask are created and
configured, the execution order of the XRLs will be: {\it XRL1, XRL3, XRL2}.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%update} Command.}

{\tt \%update} is used to update an existing instance of a
node in the configuration tree.  It is typically paired with {\tt
\%activate} - the {\tt \%activate} command is executed
after the node's children have been configured for very first time (\eg on
startup), whereas {\tt \%update} is executed if some of the node's children
have been modified (\eg via xorpsh).

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to update the configuration tree instance of this template tree
  node.

  \item If the action is {\tt program}, then the second parameter specifies
  the program to execute to update the configuration tree instance of this
  template tree node.

\end{itemize}

Note that if the value of a node is modified, only the closest {\tt \%update}
command up in the hierarchy is executed. For example, if the template tree
held the following:

\begin{tabbing}
\tt addr\=\tt ess \=\tt@: i\=\tt pv4 \{\\
    \>\tt\%create: xrl {\it XRL1};\\
    \>\tt\%activate: xrl {\it XRL2};\\
    \>\tt\%update: xrl {\it XRL3};\\
    \>\tt netmask: ipv4 \{\\
        \>\>\tt\%update: xrl {\it XRL4};\\
        \>\>\tt disable: bool \{\\
             \>\>\>\tt\%set:;\\
        \>\>\tt\}\\
    \>\tt\}\\
    \>\tt broadcast: ipv4 \{\\
        \>\>\tt\%set:;\\
    \>\tt\}\\
\tt\}
\end{tabbing}

Then when the value of {\tt disable} is modified, only
{\it XRL4} will be called. If the value of {\tt broadcast} is modified,
then {\it XRL3} will be called.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%list} Command.}

{\tt \%list} is called to obtain a list of all the configuration tree
instances of a particular template tree node.  For example, a
particular template tree node might represent the interfaces on a
router.  The configuration tree would then contain an instance of this
node for each interface currently configured.  The {\tt \%list}
command on this node would then return the list of interfaces.

\begin{itemize}
  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to return the list.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to return the list.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%

\subsubsection{The {\tt \%delete} Command.}
{\tt \%delete} is called to delete a configuration tree node and all its
children.  A node that has a {\tt \%create} or {\tt \%activate}
command should also have a {\tt \%delete} command.

\begin{itemize}
  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to delete the configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to delete the configuration tree instance of this
  template tree node.

\end{itemize}

If a node that is deleted does not have a {\tt \%delete} command, then
the {\tt \%delete} commands of its children are called instead.
This rule is applied recursively for each child that does not have
a {\tt \%delete} command.
For example, lets say A is a parent of B1 and B2, and B1 is a parent of C1.
Also, lets say that only B2 and C1 have {\tt \%delete} methods.
If we delete A, then both B2's and C1's {\tt \%delete} methods are invoked.
If, however, B1 also has a {\tt \%delete} method, then deleting A will invoke
only B1 and B2's {\tt \%delete} methods.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%set} Command.}

{\tt \%set} is called to set the value of a leaf node in the
configuration tree.

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to set the value of configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to set the value of configuration tree instance of this
  template tree node.

\end{itemize}

Note that when a new instance of a node in the configuration tree is created,
if that node has no {\tt \%create} command, then the {\tt \%set}
command (if exists) for that node is used instead.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%unset} Command.}

{\tt \%unset} is called to unset the value of a leaf node in the
configuration tree.  The value will return to its default value if a
default value is specified.

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to unset the value of configuration tree instance of this
  template tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to unset the value of configuration tree instance of this
  template tree node.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%get} Command.}

{\tt \%get} is called to get the value of a leaf node in the
configuration tree.  Normally the rtrmgr will know the value if there
is no external means to change the value, but the {\tt \%get} command
provides a way for the rtrmgr to re-sync if the value has changed.

\begin{itemize}
  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to get the value of configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to get the value of configuration tree instance of this
  template tree node.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%allow} Command.}

The {\tt \%allow} command provides a way to restrict the value of
certain nodes to specific values.

\begin{itemize}

  \item The first parameter gives the name of the variable to be restricted.

  \item The second parameter is a possible allowed value for this variable.

  \item The third parameter must be the ``\%help:'' keyword.

  \item The fourth parameter is the help string for this value.

\end{itemize}

If there is more than one possible values, each of them should be
specified by a separate {\tt \%allow} command.

For example, a node might specify an address family, which is intended
to be one of ``inet'' or ``inet6''.  The type of the node is {\tt
txt}, which would allow any value, so the allow command might allow
the rtrmgr to restrict the legal values without having to
communicate with the process providing this functionality.

A more subtle use might be to allow certain nodes to exist only if a
parent node was of a certain value.

For example:

\begin{verbatim}
      family @: txt {
          %allow: $(@) "inet" %help: "IPv4 address family";
          %allow: $(@) "inet6" %help: "IPv6 address family";
          address @: ipv4 {
              %allow: $(family.@) "inet" %help: "IPv4 address family";
              broadcast: ipv4;
          }
          address @: ipv6 {
              %allow: $(family.@) "inet6" %help: "IPv6 address family";
          }
      }
\end{verbatim}

In this case, there are two different typed versions of the ``{\tt
address @}'' node, once for IPv4 and one for IPv6.  Only one of them has
a leaf node called {\tt broadcast}.  The allow command permits the
rtrmgr to do type-checking to ensure that only the permitted
combinations are allowed.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%allow-range} Command.}

The {\tt \%allow-range} command restricts the range of values an
integer configuration item may take.  The syntax is:

\texttt{\%allow-range: }{\it varName lowValue highValue \%help: help-string}\texttt{;}

\noindent where the first parameter, \textit{varName}, gives the name
of the variable to be restricted.  This is typically
\texttt{\"\$(@)\"}.  The {\it lowValue} and {\it highVal} parameters
specify the lower and upper bound of the allowed range of values.
The {\it \%help:} is a mandatory keyword and is followed by the help
string. The help string is used for command-line completion purpose.

An example of use appears in the interface address prefix specification:

\begin{verbatim}
       address @: ipv4 {
         prefix-length: u32;
       }
       ...
       address @: ipv4 {
         prefix-length {
           %allow-range: $(@) "1" "32" %help: "The prefix length";
           %set: xrl "...";
           %get: xrl "...";
         }
       }
\end{verbatim}

If there is more than one {\tt \%allow-range} command restricting
the value of a variable, then the assigned value must belong to any
of the specified ranges.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%help} Command.}

The {\tt \%help} command specifies the CLI configuration-mode help string.
The syntax is:

\texttt{\%help: }{$\{short \mid long\}$} \texttt{"Help string"}\texttt{;}

\noindent where the first parameter, \textit{short} or \textit{long},
specifies whether this is the short-version or the long-version of the
help, and the second parameter is the help string itself.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%deprecated} Command.}

The {\tt \%deprecated} command can be used to deprecate a template tree
node and the subtree below it.
The syntax is:

\texttt{\%deprecated: } \texttt{"String with reason"}\texttt{;}

If the XORP startup configuration contains a statement that uses a
deprecated node in the template, the rtrmgr prints an error with
the string with the reason, and exits.
If, however, a third-party user program (\eg other than xorpsh) sends
to the rtrmgr configuration that contains a deprecated statement, the
rtrmgr returns an error to xorpsh, and the error message will contain
the string with the reason.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%user-hidden} Command.}

The {\tt \%user-hidden} command can be used to hide a template tree
node and the subtree below it from the user. Such node or a subtree
can be used by the rtrmgr itself for internal purpose only and is
not visible to the user (\eg via xorpsh or when saving the configuration
to a file).
The syntax is:

\texttt{\%user-hidden: } \texttt{"String with reason"}\texttt{;}

However, if the XORP startup configuration contains a statement that
uses an user-hidden node, the rtrmgr will accept
the configuration. Similarly, if a third-party user program
(\eg other than xorpsh) sends to the rtrmgr configuration that contains
an user-hidden statement, the rtrmgr would accept that statement. This
is an experimental feature may become permanent or may be disabled in
the future.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%read-only} Command.}

The {\tt \%read-only} command can be used to specify a template tree
node as read-only.
The syntax is:

\texttt{\%read-only: } \texttt{"String with reason"}\texttt{;}

or

\texttt{\%read-only:;}

Only a leaf node that contains a value can be marked as read-only.
If a node is marked as a read-only, then its value cannot be
changed from the default template value. For example, a read-only
node could be part of the startup configuration, but if its
value is different from the default template value the rtrmgr
will reject the configuration.

Note that by definition a read-only node is also permanent
(see Section \ref{sec:permanent-command}):
it cannot be deleted directly, but it will be removed if its
parent is deleted.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%permanent} Command.}
\label{sec:permanent-command}

The {\tt \%permanent} command can be used to specify a template tree
node as a permanent node that cannot be deleted.
The syntax is:

\texttt{\%permanent: } \texttt{"String with reason"}\texttt{;}

or

\texttt{\%permanent:;}

If a node is marked as permanent, the node itself cannot be deleted
directly. However, deleting the parent node will delete the permanent
node as well. Also, adding or deleting children of a permanent node
is allowed.

If a permanent node never should be deleted, then all its ancestors
should be marked as permanent.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%order} Command.}

The {\tt \%order} command provides a way to specify the ordering of
multiple nodes of the same type in the configuration.  For example, if
no ordering is specified in the template file, such as with interfaces:

\begin{verbatim}
      interfaces {
        interface @: txt {
        }
      }
\end{verbatim}

\noindent Then this template would allow the configuration for each
{\tt interface} to be displayed and configured in the order they were
entered.  For example, the configuration might be:

\begin{verbatim}
      interfaces {
        interface fxp1 {
          vif fxp1 {
             address: 10.0.0.1
          }
        }
        interface dc0 {
          vif dc0 {
             address: 10.0.1.1
          }
        }
        interface fxp0 {
          vif fxp0 {
             address: 10.0.2.1
          }
        }
      }
\end{verbatim}

\noindent The ordering of the {\tt interface} sections here is
arbitrary, in the order they were entered by the user.

\noindent In many cases this is what is desired, but in some cases such as
firewall rules, this is not desired, and the {\tt \%order} command
provides a way to enforce an ordering.

\noindent For example, a simple firewall (not the actual XORP firewall) might
use a template such as:

\begin{verbatim}
      firewall {
        interface @: txt {
           rule @: u32 {
             %order: sorted-numeric;
             permit @: txt;
             deny @:txt;
           }
         }
       }
\end{verbatim}

\noindent Thus, some configured firewall rules might be:

\begin{verbatim}
      firewall {
        interface fxp0 {
          rule 100 {
            permit "net 10.0.0.0/24"
          }
          rule 300 {
            deny "all"
          }
        }
      }
\end{verbatim}

\noindent The ordering here is now dictated by {\tt rule} number, in accordance
with the {tt \%order} command.  If a new {\tt rule 200} was
subsequently inserted, it would always be displayed and configured
after {\tt rule 100} and before {\tt rule 300}.

\noindent The available parameters for the {\tt \%order} command are:

\begin{itemize}

  \item {\tt unsorted} - the default, ordered in the order of entry.

  \item {\tt sorted-numeric} - sorted in increasing numeric interger
  order.

  \item {\tt sorted-alphabetic} - sorted in increasing alphabetic order.

\end{itemize}

\noindent Note that if {\tt sorted-numeric} is applied to a {\tt txt}
field, the sort order for non-numeric values is undefined, but numeric
values will be sorted correctly.

%%%%%%%%%%%%%%%%%%%%%%
\subsection{Template Tree Command Actions}

Template tree commands such as:
\begin{itemize}

  \item {\tt \%modinfo: start\_commit <method>;} 

  \item {\tt \%modinfo: end\_commit <method>;}

  \item {\tt \%modinfo: status\_method <method>;}

  \item {\tt \%modinfo: startup\_method <method>;}

  \item {\tt \%modinfo: shutdown\_method <method>;}

\end{itemize}

are used to specify the mechanism to be call before any configuration
change of a module, the mechanism to discover the status of a module, and so
on.
Template tree commands such as {\tt \%create}, {\tt \%activate} and
{\tt \%set} are used to specify the actions that need to be performed
when the router configuration is created or modified.

This section provides a complete listing of all the template tree
actions that the rtrmgr supports.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Template Tree {\tt xrl} Action}

The {\tt xrl} command action specifies the XRL to be executed. The XRL
and its arguments must be inside quotes and it may contains variables
that will be substituted with the particular values at execution time.
For example, if the template tree held the following:

\begin{verbatim}
    bgp-id {
        %set: xrl "$(bgp.targetname)/bgp/0.2/set_bgp_id?id:ipv4=$(@)";
    }
\end{verbatim}

Then when we set the value of {\tt bgp-id}, first the rtrmgr will substitute
{\tt \$(bgp.targetname)} with the particular value of that variable, and
{\tt \$(@)} with the value of {\tt bgp-id}. After the substitution it will
call XRL {\tt bgp/0.2/set\_bgp\_id} with argument {\tt id:ipv4} set to the
value of {\tt bgp-id}.

We could use {\tt xrl} actions to get the value of a particular variable,
store the value inside the rtrmgr and then use that value by other actions.
For example, if the template tree held the following:

\begin{verbatim}
interface {
    ...
    %modinfo: start_commit xrl "$(interface.targetname)/ifmgr/0.1/
                           start_transaction->tid:u32=$(interface.TID)";
    %modinfo: end_commit   xrl "$(interface.targetname)/ifmgr/0.1/
                           commit_transaction?tid:u32=$(interface.TID)";
    ...
    TID {
        %create:;
    }

    interface @: txt {
        %create: xrl "$(interface.targetname)/ifmgr/0.1/
                 create_interface?tid:u32=$(interface.TID)&ifname:txt=$(@)";
    }

    ...
}
\end{verbatim}

Then whenever the interface configuration is changed the {\tt start\_commit}
and {\tt end\_commit} XRLs will be call before and after performing any change
to the configuration of the module. The {\tt start\_commit} XRL will return
the transaction ID {\tt tid} of type {\tt u32}. The rtrmgr will store
that value internally in the {\tt \$(interface.TID)} local variable
(note that this variable should be declared as a leaf node without type).
Then this value can be used by other actions such as the
{\tt \%create} and the {\tt end\_commit} XRL actions in the above example.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Template Tree {\tt program} Action}

The {\tt xrl} command action specifies the external program to be executed.
The program and its arguments must be inside quotes and it may contains
variables that will be substituted with the particular values at execution
time.
For example, if the template tree held the following:

\begin{verbatim}
    foo {
        %set: program "/bin/echo -n '$(@)' >> /tmp/file.txt";
    }
\end{verbatim}

Then when we set the value of {\tt foo}, first the rtrmgr will substitute
{\tt \$(@)} with the value of {\tt foo}. After the substitution it will
call program {\tt /bin/echo} with argument {\tt -n} and the value
of {\tt foo}. The result of this command will be appended to file
{\tt /tmp/file.txt}.

We could use {\tt program} actions to store the {\tt stdout} and {\tt stderr}
output of a command inside the rtrmgr and then use those values by other
actions.
For example, if the template tree held the following:

\begin{verbatim}
rtrmgr {
    ...
    CONFIG {
        %create:;
    }
    CONFIG_STDERR {
        %create:;
    }

    load {
        %create:;
        %set: program "/bin/cat '$(@)' ->
              stdout=$(rtrmgr.CONFIG)&stderr=$(rtrmgr.CONFIG_STDERR)";
    }
    save {
        %create:;
        %set: program "/bin/echo -n '$(rtrmgr.CONFIG)' > '$(@)'";
    }
    ...
}
\end{verbatim}

Then whenever we change the value of variable {\tt load}, the external
program {\tt /bin/cat} will be executed with the value of that variable as
its argument. The rtrmgr will store the stdout and stderr output of
that program internally inside local variables {\tt \$(rtrmgr.CONFIG)}
and {\tt \$(rtrmgr.CONFIG\_STDERR)} respectively (note that those variables
should be declared as leaf nodes either with or without type).
Then those values can be used by other actions such as the {\tt \%set}
action for the {\tt save} node in the above example.

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The Configuration File}

Whereas the template files inform the rtrmgr as the {\it possible}
configuration of the router, the configuration file provides the
specific startup configuration to be used by this specific router.
The syntax is similar to, but not the same as, that of template files -
the differences are intentional - template files are intended to be
written by software developers, whereas configuration files are
intended to be written by network managers.  Hence the syntax of
configuration files is simpler and more intuitive, but less powerful.
However, both specify the same sort of tree structure, and the nodes
in the configuration tree must correspond to the nodes in the template
tree.

An example fragment of a configuration file might be:

\begin{verbatim}
protocols {
  ospf {
    router-id: 1.2.3.4
    mospf
    area 1.2.3.27 {
      stub
      interface fxp1 {
        hello-interval: 10
      }
      interface fxp2
    }
  }
}
\end{verbatim}

Note that unlike in the template tree, semicolons are not needed in the
configuration tree, and that line-breaks are significant.

The example fragment of a configuration file above will construct the
following configuration tree from the template tree example given
earlier:

\begin{figure}[htb]
\centerline{\includegraphics[width=0.7\textwidth]{figs/config}}
\vspace{.05in}
%\caption{\label{overview}Overview of XORP processes}
\end{figure}

Note that configuration tree nodes have been created for {\tt
dead-interval} and (in the case of fxp1) for {\tt hello-interval} even
though this was not mentioned in the configuration file.  This is
because the template tree contains a default value for this leaf node.
Also, in case of configuring a boolean variable (\eg of type {\tt bool} or
{\tt toggle}) such as {\tt mospf}, typing the variable name itself
(\eg \verb=mospf=) is equivalent to assigning it value of {\tt true}
(\eg \verb=mospf: true=).

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Command Line Interface: xorpsh}

The rtrmgr process is the core of a XORP router - it starts and stops
processes and keeps track of the configuration.  To do its task, it
must run as root, whereas most other XORP processes don't need
privileged operation and so can be sandboxed.  This makes the rtrmgr
process the single most critical point from a security point of view.
Thus we would like the rtrmgr to be as simple as
possible\footnote{Unfortunately the router manager is not simple as we
would like.}, and to isolate it from possibly hostile input as far as
is reasonable.

For these reasons we do not build a command line interface directly
into the rtrmgr, but instead use an external process called {\tt
xorpsh} to interact with the user, while limiting the rtrmgr's
interaction with xorpsh to simple authentication mechanisms, and
exchanges of configuration tree data.  Thus the command line interface
architecture looks like:

\begin{figure}[htb]
\centerline{\includegraphics[width=0.7\textwidth]{figs/xorpsh}}
\vspace{.05in}
%\caption{\label{overview}Overview of XORP processes}
\end{figure}

The interface between the rtrmgr and a xorpsh instance consists of
XRLs that the xorpsh may call to query or configure rtrmgr, and a few
XRLs that the rtrmgr may asynchronously call to alert the xorpsh
process to certain events.

The rtrmgr exports the following XRLs that may be called by xorpsh:

\begin{description}

  \item{\tt register\_client} \\This XRL is used by a xorpsh instance to
  register with the rtrmgr.  In response, the rtrmgr provides the name
  of a file containing a nonce - the xorpsh must read this file and
  return the contents to the rtrmgr to authenticate the user.

  \item{\tt authenticate\_client} \\Xorpsh uses this to complete the
  authentication process.

  \item{\tt get\_running\_config} \\Xorpsh uses this to request the
  current running configuration from the rtrmgr.  The response is text
  in the same syntax as the rtrmgr configuration file that provides the
  rtrmgr's view of the configuration.

  \item{\tt enter\_config\_mode} \\A xorpsh process must be in
  configuration mode to submit configuration changes to the rtrmgr.
  This XRL requests that the rtrmgr allows the xorpsh to enter
  configuration mode.  Not all users have permission to enter
  configuration mode, and it is also possible that a request may be
  refused because the configuration is locked.

  \item{\tt get\_config\_users} \\Xorpsh uses this to request the list of
  users who are currently in configuration mode.

  \item{\tt apply\_config\_change} \\Xorpsh uses this to submit a request
  to change the running configuration of the router to the rtrmgr.  The
  change consists of a set of differences from the current running
  configuration.

  \item{\tt lock\_config} \\Xorpsh uses this to request an exclusive
  lock on configuration changes.  Typically this is done just prior to
  submitting a set of changes.

  \item{\tt unlock\_config} \\Unlocks the rtrmgr configuration that was
  locked by a previous call to {\tt lock\_config}.

  \item{\tt lock\_node} \\Xorpsh uses this to request a lock on
  configuration changes to a specific config tree node.  Usually this
  will be called because the user has made local changes to the config
  but not yet committed them, and wishes to prevent another user making
  changes that conflict.  Locking is no substitute for human-to-human
  configuration, but it can alert users to potential problems.

  {\it Note: node locking is not implemented yet.}

  \item{\tt unlock\_node} \\Xorpsh uses this to request a lock on a
  config tree node be removed.

  \item{\tt save\_config} \\Xorpsh uses this to request the
  configuration be saved to a file.  The actual save is performed by the
  rtrmgr rather than by xorpsh, but the resulting file will be owned by
  the user running this instance of xorpsh, and the file cannot
  overwrite files that this user would not otherwise be able to
  overwrite.

  \item{\tt load\_config} \\Xorpsh uses this to request the rtrmgr reloads
  the router configuration from the named file.  The file must be
  readable by the user running this instance of xorpsh, and the user
  must be in configuration mode when the request is made.

  \item{\tt leave\_config\_mode} \\Xorpsh uses this to inform rtrmgr that
  it is no longer in configuration mode.

\end{description}

\vspace{0.2in}
Each xorpsh process exports the following XRLs that the rtrmgr can use
to asynchronously communicate with the xorpsh instance:

\begin{description}

  \item{\tt new\_config\_user} \\Rtrmgr uses this XRL to inform all
  xorpsh instances that are in config mode than another user has entered
  config mode.

  \item{\tt config\_change\_done} \\When a xorpsh instance submits a
  request to the rtrmgr to change the running config or to load a config
  from a file, the rtrmgr may have to perform a large number or XRL calls
  to implement the config change.  Due to the single-threaded nature of
  XORP processes, the rtrmgr cannot do this while remaining in the {\tt
  apply\_config\_change} XRL, so it only performs local checks on the
  sanity of the request before returning success or failure - the
  configuration will not have actually been changed at that point.  When
  the rtrmgr finishes making the change, or when failure occurs part way
  through making the change, the rtrmgr will call {\tt
  config\_change\_done} on the xorpsh instance that requested the change
  to inform it of the success or failure.

  \item{\tt config\_changed} \\When multiple xorpsh processes are
  connected to the rtrmgr, and one of them submits a successful change
  to the configuration, the differences in the configuration will then
  be communicated to the other xorpsh instances to keep their version of
  the configuration in sync with the rtrmgr's version.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Operational Commands and xorpsh}

Up to this point, we have been dealing with changes to the router
configuration.  Indeed this is the role of the rtrmgr process.
However a router's command line interface is not only used to change
or query the router configuration, but also to learn about the dynamic
state of the router, such as link utilization or routes learned by a
routing protocol.  To keep it as simple and robust as possible, the
rtrmgr is not involved in these \textit{operational mode} commands.
Instead these commands are executed directly by a xorpsh process
itself.

To avoid the xorpsh implementation needing in-built knowledge of
router commands, the information about operational mode commands is
loaded from another set of template files.  A simple example might be:

\begin{verbatim}
show interfaces $(interfaces.interface.*) {
        %command: "path/to/show_interfaces -i $3" %help: HELP;
        %module: fea;
        %opt_parameter: "brief" %help: BRIEF;
        %opt_parameter: "detail" %help: DETAIL;
        %opt_parameter: "extensive" %help: EXTENSIVE;
        %tag: HELP "Show network interface information";
        %tag: BRIEF "Show brief network interface information";
        %tag: DETAIL "Show detailed network interface information";
        %tag: EXTENSIVE "Show extensive network interface information";
}
show vif $(interfaces.interface.*.vif.*) {
        %command: "path/to/show_vif -i $3" %help: "Show vif information";
        %module: fea;
        %opt_parameter: "brief" %help: "Show brief vif information";
        %opt_parameter: "detail" %help: DETAIL;
        %opt_parameter: "extensive" %help: EXTENSIVE;
        %tag: DETAIL "Show detailed vif information";
        %tag: EXTENSIVE "Show extensive vif information";
}
\end{verbatim}

This template file defines two operational mode commands:
``{\tt show interfaces}'' and ``{\tt show vif}''.

The ``show interfaces'' command takes one mandatory parameter, whose
value must be the name of one of the configuration tree nodes taken
from the variable name wildcard expansion {\tt
\$(interfaces.interface.*)}.  Thus if the router had config tree nodes
called ``{\tt interfaces interface xl0}'', and ``{\tt interfaces interface
xl1}'', then the value of the mandatory parameter must be either {\tt
xl0} or {\tt xl1}.

Additional optional parameters might be {\tt brief}, {\tt detail}, or
{\tt extensive} - the set of allowed optional parameters is specified
by the {\tt \%opt\_parameter} commands.

The {\tt \%command} command indicates the program or script (and its
arguments) to be
executed to implement this operational command - the script should return
human-readable output preceded by a MIME content type indicating
whether the text is structured or not\footnote{Only {\tt text/plain}
is currently supported.}.
If the command specification contains any positional arguments
(\eg {\tt \$0}, {\tt \$1}, {\tt \$2}) they are resolved by substituting
them with the particular substring from the typed command line command:
{\tt \$0} is substituted with the complete string from the command line,
{\tt \$1} is substituted with the first token from the command line,
{\tt \$2} is substituted with the second token from the command line,
The resolved positional arguments along with the remaining arguments
(if any) are passed to the executable command.
For example, if the user types ``show interfaces xl0'', the xorpsh might invoke
the {\tt show\_interface} command using the Unix command line:

\begin{verbatim}
    path/to/show_interfaces -i xl0
\end{verbatim}

The pathname to a command must be
relative to the root of the XORP tree. The ordering in computing the root of
the tree is: (a) the shell environment XORP\_ROOT (if exists); (b) the parent
directory the xorpsh is run from (only if it contains the
etc/templates and the xrl/targets directories); (c) the XORP\_ROOT value as
defined in config.h (currently this is the installation directory, and
defaults to ``/usr/local/xorp'').

The command {\tt \%module} indicates that this operational command should
only be available through the CLI when the router configuration has required
that the named module has been started.
If the {\tt \%module} command is missing, then this operational command
is always enabled.

The command {\tt \%help} is used to specify the CLI help for each
CLI command or the optional parameters.
It must be on the same line as the {\tt \%command} or the
{\tt \%opt\_parameter} commands. If the argument after the {\tt \%help}
command is in quotes, then it contains the help string itself.
Otherwise, the argument is the name of the tag that contains the help
string.

The command {\tt \%tag} is used to specify the help string associated
with each tag. For example, statement:

\begin{verbatim}
        %command: "path/to/show_vif -i $3" %help: HELP;
        %tag: HELP "Show vif information";
\end{verbatim}

is equvalent with:

\begin{verbatim}
        %command: "path/to/show_vif -i $3" %help: "Show vif information";
\end{verbatim}

\textit{Note: currently there is no security mechanism restricting
access to operational mode commands beyond the restrictions imposed by
Unix file permissions.  This is not intended to be the long-term
situation.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     APPENDIX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
\section{Modification History}

\begin{itemize}

  \item December 11, 2002: Initial version 0.1 completed.

  \item March 10, 2003: Updated the version to 0.2, and the date.

  \item June 9, 2003: Updated to match XORP release 0.3.

  \item August 28, 2003: Updated to match XORP release 0.4.

  \item November 6, 2003: Updated the version to 0.5, and the date.

  \item July 8, 2004: Updated to match XORP release 1.0.

  \item January 27, 2005: Removed MFEA+MRIB-related text, because the MFEA
  does not deal with the MRIB information anymore.

  \item April 13, 2005: Updated to match XORP release 1.1.

  \item March 8, 2006: Updated to match XORP release 1.2.

  \item August 2, 2006: Updated the version to 1.3, and the date.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     BIBLIOGRAPHY
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bibliography{../tex/xorp}
\bibliographystyle{plain}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}