rtrmgr.tex

xorp源码hg

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.

  \item March 20, 2007: Updated the version to 1.4, and the date.

\end{itemize}

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

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