rtrmgr.tex

来自「BCAST Implementation for NS2」· TEX 代码 · 共 668 行 · 第 1/2 页

    \>\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 \%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.
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call 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.
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call to delete the configuration tree instance of this template tree
node.
\end{itemize}

\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.
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call to set the value of configuration tree instance of this template
tree node.
\end{itemize}
\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.
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call 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.
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call 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 remaining parameters are a list of possible allowed values for
this variable.
\end{itemize}
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
text}, 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 @: text {
        %allow: $(@) "inet" "inet6";
        address @: ipv4 {
          %allow: $(family.@) "inet";
          broadcast: ipv4;
        }
        address @: ipv6 {
          %allow: $(family.@) "inet6";
        }
      }
\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.
\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.
\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 yet implemented.}
\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 interface $(interfaces.interface.*) {
        %command: show_interface;
        %module: fea;
        %opt_parameter: brief;
        %opt_parameter: detail;
        %opt_parameter: extensive;
}
show vif $(interfaces.interface.*.vif.*) {
        %command: show_vif;
        %module: fea;
        %opt_parameter: brief;
        %opt_parameter: detail;
        %opt_parameter: extensive;
}
\end{verbatim}
This template file defines two operational mode commands: ``{\tt show
interface}'' and ``{\tt show vif}''.

The ``show interface'' 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 to be
executed to implement this 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.}.  The entire command line typed by the user
is passed into the command.  Thus the xorpsh might invoke the {\tt
show\_interface} command using the Unix command line:
\begin{verbatim}
    path/to/show_interface show interface xl0 brief
\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 command should only be
available through the CLI when the router configuration has required
that the named module has been started.

\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.}
\end{document}