error_handling.tex

xorp源码hg

If the \rtrmgr/\finder dies then all bets are off and all processes
should exit apart from the \xorpsh.

If a \xorp process exits unexpectedly the \rtrmgr/\finder should
attempt to restart the process.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{FEA - Forwarding Engine Abstraction}

The FEA primarily accepts routes from the RIB and places them in the
kernel. The FEA should tag all routes that it has installed in the
kernel.  On restart, the FEA should remove all routes that a previous
incarnation of the FEA has placed in the kernel. When an FEA is
exiting it should attempt to remove all routes that it has installed
in the kernel.

The FEA process should register interest in the RIB. If the RIB fails
the FEA should withdraw all routes that the RIB has sent to it.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{MFEA - Multicast Forwarding Engine Abstraction}

The MFEA is multicast analogue to the unicast FEA. If should be noted
that typically the MFEA would be part of the FEA process.

Similar to the FEA, on restart or exit the MFEA should remove all
multicast forwarding entries that were installed in the kernel. Note
that the MFEA does not contain a copy of the multicast forwarding entries
that were installed in the kernel, so it should utilize a
mechanism that removes all multicast forwarding entries at once.  In
case of UNIX-based systems, closing the multicast routing socket will
automatically remove all entries.

If the multicast routing process that has installed the multicast
forwarding entries exits, then the MFEA should remove all multicast
forwarding entries from the kernel. Currently, PIM is the only
multicast routing process. In the future, the XORP multicast routing
architecture may contain a special coordinator among all multicast
routing protocol instances, analogous to the function of the unicast
RIB process. If that coordinator exits, the MFEA should remove all
multicast forwarding entries from the kernel.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{RIB - Routing Information Base}

Routes from the routing processes are sent to the RIB; the winners are
sent to the FEA.

The RIB should register interest in the FEA. If the FEA fails the RIB
should exit. All routing processes that interact with the RIB should,
on detecting the shutdown of the RIB, also terminate gracefully.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{IGMP/MLD}

If the FEA/MFEA process exits then this process should exit.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{PIM}

If the RIB or the FEA/MFEA process exits then this process should exit.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{BGP}

Currently the only other process in the system that BGP interacts
with is the RIB. If the BGP process detects that the RIB has died then
it should gracefully terminate its sessions and exit.

In the future the TCP connections that BGP makes will be mediated
through FEA, at which time the BGP process should also register
interest in the state of the FEA. If the BGP process detects the death
of the FEA it should exit immediately.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{RIP}

The RIP process should register interest in the FEA and the RIB. If
the RIB dies then the RIP process should attempt to exit gracefully.
If the FEA dies the RIP process should exit immediately.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{IS-IS}

The IS-IS process should register interest in the FEA and the RIB. If
the RIB dies then the IS-IS process should attempt to exit gracefully.
If the FEA dies the IS-IS process should exit immediately.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{OSPF}

The OSPF process should register interest in the FEA and the RIB. If
the RIB dies then the OSPF process should attempt to exit gracefully.
If the FEA dies the OSPF process should exit immediately.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{\label{xorpsh}\xorpsh}

The \xorpsh provides a command line interface to the XORP router.
Other processes in the system exiting should never cause it to
exit. The \rtrmgr/\finder process exiting should generate
warning output to the user and then the \xorpsh should wait for the
router to restart.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{XRL Communication Errors}

Interprocess communication in \xorp is achieved using XRLs. In this
section we will consider what should be done when an XRL call fails
due to a communication error.

XRLs can be sent over unreliable transports such as UDP or reliable
transports such as TCP. The type of transport used is decided by the
XRL library based on the specification of each interface.  For the
purposes of error handling, the reliable and unreliable transports are
the same in all regards, except that reliable transports in XORP never
explicitly report a timeout error.

XRL communication is asynchronous: applications request the dispatch
of an XRL and expect to have a callback invoked when the dispatch
result is available.  This presents opportunities for immediate and
deferred error indications.  Immediate error indications occur when
the request for XRL dispatch is made: the canonical example occurring
when no more buffer space is available within the XRL library is
available. An application is able to detect these errors
synchronously: the dispatch request indicates an error in its return
value.  Deferred error indications happen through the dispatch
callbacks.  These callbacks are required to take an XrlError object as
an argument.  An XrlError object is comprised of an enumerated error
code and an optional string containing specific information relating
to the error.  The set of enumerated error codes is presented below.

Immediate and deferred errors are exclusive.  If the \xt dispatching
an XRL got an immediate error, it will not receive a callback
indicating a deferred error.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection*{Standard Dispatch XRL Error Values}

The standard XRL return values are returned to the requesting \xt by
the dispatching \xt.  When any of these values are returned, the XRL
communication has been successful.

\begin{description}

  \item [OKAY] XRL dispatch successful.  Additional parameters in
  XRL callback contain return values.

  \item [COMMAND\_FAILED] XRL reached dispatcher, but could not be
  dispatched. The reason for failure may be specified in the note
  associated with the XrlError object.

  \item [BAD\_ARGS] XRL reached dispatcher, but argument types did not match
  those expected by the dispatcher.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection*{Finder XRL Error Values}

\begin{description}

  \item [NO\_FINDER] This error occurs when an \xt cannot communicate
  with the \finder. This always indicates a serious problem with the
  router, as the \finder should always be present. The application
  SHOULD treat this error as fatal.

  \item [RESOLVE\_FAILED] This error occurs when a \xt process tries to
  resolve an XRL the \finder has no result for.  This may be because the
  target specified in the XRL does not exist or exists, but is still in
  the process of registering the XRL it exports.

  RESOLVE\_FAILED errors may happen because of a benign cause, namely
  that processes started up in a less than perfect order, so a target's
  user has initialized before the target itself. Applications SHOULD
  handle this type of transient RESOLVE\_FAILED error with a
  retransmission strategy.  Applications may avoid this error by using
  the Finder event observer interface to detect when the particular
  target becomes ready.

  \item [NO\_SUCH\_METHOD] This error occurs when the named \xt is running and
  has registered 
  it's XRLs, but it does not support the method named in the XRL.
  NO\_SUCH\_METHOD generally indicates a version mismatch between two
  processes. This error may be considered fatal, or (for example) the
  application might react by trying to access an older version of the
  interface. The application can expect, however, that NO\_SUCH\_METHOD
  errors are not transient: If an XRL access gets a NO\_SUCH\_METHOD
  error, then that XRL will always result in a NO\_SUCH\_METHOD error,
  at least until the target process restarts.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection*{Transport and Internal Xrl Error Values}

\begin{description}

  \item [SEND\_FAILED] The underlying XRL transport mechanism has failed.
  For example, the TCP connection has been reset, or a UDP connection
  gets a port-unreachable message. The expectation is that no further
  communication with the specific endpoint will succeed.

  \item [SEND\_FAILED\_TRANSIENT] This error occurs when the XRL library
  temporarily cannot send a particular XRL. Usually, this will be
  because of congestion or a slow receiver: the kernel has run out of
  buffer space. Note that the XRL library performs some buffering
  itself, to ensure that XRL requests are either completely transmitted
  or not transmitted at all.
  \emph{Note: The XRL library does not yet implement this error.}

  \item [REPLY\_TIMED\_OUT] -- The target did not reply within a
  transport-protocol-specific period of time. Possible reasons include
  network congestion, peer failure, network interface failure, and so
  on. As in all network communications, when a timeout occurs we don't
  know if the last unacknowledged XRL request was received and processed
  by the peer. This error occurs in unreliable transmit only.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Handling XRL Errors}

XRLs may be directed to a class of target or a particular instance of
a target.  The first instance of a target that registers with the
\finder is considered to be the primary instance of its class and XRLs
addressed to that are directed to that instance.  The XRL library MAY
hide certain REPLY\_TIMED\_OUT and SEND\_FAILED errors for XRLs
directed towards classes, \ie should the instance which is acting as
the primary instance fail or exit, then another instance in that
class, will receive the class directed XRL requests.

%When communication with a particular
%instance of the target fails, the XRL library thus MAY search for
%another instance by contacting the \finder. The XRL library MUST NOT