snmp_overview.tex

xorp源码hg

Figure \ref{fig:xorp-if-diag} illustrates the functionality implemented by 
\texttt{xorp\_if\_mib\_module}.

\begin{figure}
  \begin{center}
    \includegraphics[width=1\textwidth]{figs/snmp_fig2}
  \end{center}
  \caption{Functionality of xorp\_if\_mib\_module}
  \label{fig:xorp-if-diag}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Modifying XORP's configuration from within a MIB module}

MIB modules use XORP's IPC library \cite{xorp:xrl} to communicate to XORP
processes.  Each MIB module has the responsibility to pull the relevant
management information from the appropriate process (\eg BGP MIB data from BGP
process).  For that effect, the MIB module must use the XRL Interface
supported by the XRL targets it needs to communicate to (see
\cite{xorp:xrl_interfaces} for details on how to subclass XRL Interface Client
classes).  MIB modules, though, MUST not modify any configuration settings by
accessing the process directly.  The current state of configuration is
maintained by the router manager process, so bypassing it would cause the real
and the recorded configurations to be out of sync.  Instead, configuration
changes should be requested to the router manager via configuration commands,
that is, XRLs such as the ones appearing in the template files (see
xorp/etc/templates/*.tp).

Figure \ref{fig:mib-class-diag} illustrates how the MIB modules should read and
change XORP configuration.

\begin{figure}
  \begin{center}
    \includegraphics[width=1\textwidth]{figs/snmp_fig1}
  \end{center}
  \caption{MIB module interactions with the router manager}
  \label{fig:mib-class-diag}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{A reference implementation of a MIB module}

So far we've talked Net-SNMP configuration.  In this section we'll cover
how to write a MIB module.  Currently (March 2007) we provide a full
implementation of RFC 1657, the MIB for BGP4.  You will find the MIB module
files in xorp/mibs/bgp4\_mib\_1657*.  What follows is a description the tools
and process followed to implement this module.  You should refer to the
kdoc documentation as well as the source itself for more details.   

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The textual MIB definition file}

The first step to write a MIB module should be writing or getting the ASN.1 MIB
definition file.  If you are implementing an existing protocol, chances are
that there is already a published RFC with the MIB definition for it.  In this
section we'll use BGP4-MIB to illustrate the process of writing a MIB module,
which is published in RFC 1657 and you will find in
xorp/mibs/textual/BGP4-MIB.txt.

You will also have to  make your textual MIB file accessible to the Net-SNMP
tools.  See the \texttt{mibs} and \texttt{mibdirs} directives in the man page
snmp.conf(5).  One way to do this is to copy our MIB onto the default
directory, and then set the MIBS environment variable:

\begin{verbatim}
$ cp BGP4-MIB.txt /usr/local/share/snmp/mibs
$ export MIBS=+BGP4-MIB
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Net-SNMP handlers}

Net-SNMP 5.x.x uses handlers to process SNMP requests.  When a MIB module is
loaded, it registers one or more handlers (callbacks) on a given OID in the OID
tree.  When a request arrives for that OID subtree, the registered handlers
are called in sequence until the request is fully processed.  There are
multiple pre-written handlers (helpers, in Net-SNMP nomenclature) that deal
with certain parts of the processing.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Using mib2c}

Net-SNMP provides what is usually termed as ''MIB compiler'' (\texttt{mib2c}),
a tool that will read MIB ASN.1 definition files and generate C code templates
to ease the development of handlers.  \texttt{mib2c} takes a configuration
file as a parameter that will determine which helper handlers to use.

The MIB compiler is not installed by default with Net-SNMP.  If you have
Net-SNMP installed in your system and you invoke \texttt{mib2c} you'll probably
get this message:

\begin{verbatim}
ERROR: You don't have the SNMP perl module installed.  Please obtain
this by getting the latest source release of the net-snmp toolkit from
http://www.net-snmp.org/download/ .  Once you download the source and
unpack it, the perl module is contained in the perl/SNMP directory.
See the INSTALL file there for instructions.
\end{verbatim}

This is what it took to install it in a FreeBSD system:

\begin{verbatim}
$ pwd
/usr/ports/net/net-snmp/work/net-snmp-5.0.8/perl
$ perl Makefile.PL ; gmake ; gmake install
Writing Makefile for NetSNMP::default_store
Writing Makefile for NetSNMP::ASN
Writing Makefile for NetSNMP::OID
...
\end{verbatim}

Now you can invoke \texttt{mib2c}.  The following command says ''create a
template C file for bgpVersion, which is a scalar, and  name it
bgp4\_mib\_1657\_bgpversion''.


\begin{verbatim}
$ mib2c -i -c mib2c.scalar.conf -f bgp4_mib_1657_bgpversion bgpversion
writing to bgp4_mib_1657_bgpversion.h
writing to bgp4_mib_1657_bgpversion.c
\end{verbatim}

In a similar way, if we want to generate C templates for a SNMP table we would
use:

\begin{verbatim}
$ mib2c -i -c mib2c.iterate.conf -f bgp4_mib_1657_bgppeertable bgpPeerTable
writing to bgp4_mib_1657_bgppeertable.h
writing to bgp4_mib_1657_bgppeertable.c
\end{verbatim}

Note that although there are other conf files, only the two presented in this
section can be used with XORP's asynchronous architecture.  You can find
details on those files by omitting the -c option when invoking \texttt{mib2c}. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Using delegated requests}
  
The asynchronous nature of XORP communications prevents handlers from
processing SNMP requests synchronously.  Handlers initiate XRL requests for
other XORP processes, and return control to the SNMP agent before the reply is
received.  Net-SNMP allows that by providing the \texttt{delegated} flag in the
SNMP request structure.  The agent will not send a reply to a request for as
long as that flag is set.  In XORP MIBs, you would normally set the delegated
flag when your handler is called, and clear it whenever the XRL callback who
receives the data from a XORP process is executed.  There is an additional
example of a delegated request in

\verb1http://www.net-snmp.org/tutorial-5/agent/delayed__instance_8c-example.html1\footnote{This
example uses the function \texttt{netsnmp\_handler\_check\_cache()} which you
will see that it's not used in our code.  The reason is that it is incompatible
with the code generated by mib2c.iterate.conf}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Caching tables inside the agent}

SNMP is layered on a connectionless protocol (UDP).  This means that no state
can be maintained between two different requests.  A consequence of this is
that a table must be searched for \emph{each} element on the table,
regardless on whether the table is sorted or not.  Now, how efficient is this
search?

The code generated with \texttt{mib2c.iterate.conf} is designed to deal with
unsorted tables, so a GETNEXT request for a single element in the table
produces $num\_rows$ calls to the user provided handlers, or
$O(num\_cols*num\_rows^{2})$ to read the entire table.  Althought this is
acceptable for most of the small tables typically found in MIB modules, it is
prohibitive for large tables, such as \texttt{BGP4-MIB::bgp4PathAttrTable}
($\approx100,000$ rows).  

To address this problem, we have cached \texttt{BGP4-MIB::bgp4PathAttrTable} 
inside the SNMP agent process space in a sorted data structure.  This
eliminates the need to use XRLs to process an SNMP request, and reduces the
complexity to read the entire table to $O(num\_cols*num\_rows*log(num\_rows))$.
The configuration file used to generate the code for cached tables is
\texttt{mib2c.array-user.conf}.

There are plans to include caching built in inside Net-SNMP.  When that
happens, this strategy may not longer be necessary. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Launching Net-SNMP via the router manager}

You can have the rtrmgr process start the SNMP agent.  In order to do that, you
should modify your agent snmpd.conf (by default in /usr/local/share/snmp) to
load xorp\_if\_module at start up. After that, you can modify your config.boot
file to load MIB modules when the agent is started, or to do it whenever a
particular protocol comes up. 

See \texttt{\$\{XORP\}/etc/templates/snmp.tp} for definition of the SNMP
configuration tree.


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

\begin{itemize}

  \item June 9, 2003: Initial version 0.3 completed.

  \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 the version to 1.0, and the date.

  \item April 13, 2005: Updated the version to 1.1, and the date.

  \item March 8, 2006: Updated the version to 1.2, and the date.

  \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}