rtrmgr.tex

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

\documentclass[11pt]{article}
\usepackage{graphicx}
\usepackage{times}
\textwidth 6.5in
\topmargin 0.0in
\textheight 8.5in
\headheight 0in
\headsep 0in
\oddsidemargin 0in

\title{XORP Router Manager Process (rtrmgr) \\
\vspace{1ex}
Version 0.5}
\author{ XORP Project					\\
	 International Computer Science Institute	\\
	 Berkeley, CA 94704, USA			\\
	 {\it [e-mail]}
}
\date{November 6, 2003}

%\twocolumn
\begin{document}
\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}.
\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 XRLs that need to be called to configure the process
just started.  These XRLs are then called, one after another, with the
successful completion of one XRL triggering the calling of the next.
Some processes may require calling a transaction start XRL before
configuration, and a transaction complete XRL 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: int;
    area @: ipv4 {
      stub: toggle = false;
      interface @: text {
        disable: toggle = false;
        hello-interval: uint = 30;
        dead-interval: uint = 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.  Here 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 uint} (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";
  router-id {
    %set: xrl "ospf/ospf/0.1/set_router_id?id:u32=$(@)";
    %get: xrl "ospf/ospf/0.1/get_router_id->id:u32";
  }
  area @ {
    %create: xrl "ospf/ospf/0.1/add_or_configure_area?
                  area_id:u32=$(area.@)&is_stub:bool=$(@.stub)";
    %delete: xrl "ospf/ospf/0.1/delete_area?area_id:u32=$(area.@)";
  }
}
\end{verbatim}
The first three 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
that this functionality is provided by the module called {\tt ospf},
that this module depends on the module called {\tt rib}, and that the
software in {\tt ospfd/xorp/ospfd} is the software to run to
provide this module.

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/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 the
variable {\tt \$(@)}.  All variables take the form {\tt \$(}...{\tt
)}.   

The variable {\tt \$(@)} means the value of the
current node, so if 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.  

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''.

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, and to indicate which other modules this software depends on
being running.
\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}
\subsection{Template Tree Node Types}
The following types are currently supported for template tree nodes:
\begin{description}
\item{\tt uint}\\
Unsigned 32 bit integer
\item{\tt int}\\
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 ipv4\_prefix}\\ An IPv4 address and prefix length in the
conventional format.  E.g.: {\tt 1.2.3.4/24}.
\item{\tt ipv6}\\
An IPv6 address in the canonical colon-separated human-readable format.
\item{\tt ipv6\_prefix}\\
An IPv6 address and prefix in the conventional format. E.g.: {\tt
fe80::1/64}
\item{\tt macaddr}\\
An MAC address in the conventional colon-separated hex format.  E.g.:
{\tt 00:c0:4f:68:8c:58}
\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: startcommit }{\it XRL}}  \\The {\tt startcommit} subcommand takes one additional
parameter, and gives the XRL to call before performing
any change to the configuration of the module.
\item {{\tt \%modinfo: endcommit }{\it XRL}}  \\The {\tt endcommit} subcommand takes one additional
parameter, and gives the XRL to call to complete any
change to the configuration of the module.  startcommit and
endcommit are optional.  They provide a way to make batch changes to a
module configuration as an atomic operation.
\item {{\tt \%modinfo: statusmethod }{\it method}}  \\The {\tt
statusmethod} subcommand indicates the mechanism to be used to
discover the status of the module.  The only method current supported
is {\tt xrl} which indicates usage of the common interface {\tt
get\_status} XRL.
\item {{\tt \%modinfo: shutdownmethod }{\it method}}  \\The {\tt
shutdownmethod} subcommand indicates the mechanism to be used to
gracefully shutdown the module.  The only method current supported
is {\tt xrl} which indicates usage of the common interface {\tt
shutdown} XRL.  If the process does not then transition to {\tt
PROC\_SHUTDOWN} state, the rtrmgr will then kill the process.
\end{description}
\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.  
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call to create the new configuration tree instance of this template
tree node.
\end{itemize}

\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.
\item If the action is {\tt xrl}, then the second parameter gives the XRL to
call 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}\\