rtrmgr.tex

xorp源码hg

%
% $XORP: xorp/docs/rtrmgr/rtrmgr.tex,v 1.54 2007/03/15 00:43:16 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.4}
\author{ XORP Project					\\
	 International Computer Science Institute	\\
	 Berkeley, CA 94704, USA			\\
         {\it http://www.xorp.org/}			\\
	 {\it [e-mail]}
}
\date{March 20, 2007}

\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