Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Route Table Service

Service Overview

ICOS has an application level routing table. This routing table, sometimes referred to as the RIB, collects routes from multiple sources, including local routes, static routes, and routes from dynamic routing protocols. Using the industry standard route preference mechanism, ICOS selects the best route to each destination prefix and installs the best routes in the hardware forwarding table. This RPPI service allows applications to query and modify the application routing table, and thus indirectly query and modify the forwarding table.

Protocol Registration

Each route in the application routing table is associated with a protocol and has a specific route type. The ICOS user interface identifies routes by their protocol and route type. Applications can register new protocols and route types to distinguish application routes from routes internal to ICOS.

RPPI offers RPC APIs to register a protocol and to register a route type. These APIs return a protocol ID or route type ID that the application uses later to add and remove routes or to deregister. The APIs allow the user to specify text strings used to refer to the protocol or route type in the ICOS CLI. An application may register multiple route types with the same protocol name.

In response to a registration call, RPPI assigns a unique protocol ID and a unique route type ID. These are returned in the last two parameters of the registration call. When an application adds, modifies, or deletes a route in ICOS, it should include a registered route type ID as part of the route specification.

An application can deregister a routing protocol or an individual route type. Before deregistering a route type, an application should remove all routes with that route type. When the last route type for a routing protocol is deregistered, RPPI automatically removes the protocol.

Routing Table APIs

RPPI includes APIs to perform the following actions on the routing table:

The route add, delete, and modify RPC APIs include as input a description of the route. One field in this description is the route type ID. The route type ID should be an ID provided by RPPI when the application registered as a routing protocol. While the routing table will accept routes with unknown route types, the user interface will not recognize and identify them as it does routes with registered route types.

Through RPPI, applications may learn routes they did not install. RPPI provides an API to get the protocol name and route type name for the route's route type. Applications use these names to determine whether a route is a connected route or an OSPF route, for example.

APIs that take a route as input or output use a separate parameter for the route's next hops. The next hops are encoded in an open_buffdesc. When a route is an input to an API, the route parameter indicates the number of next hops and the open_buffdesc parameter is an array of next hops (onpNextHop_t). When a route is an output to an API, the caller creates an open_buffdesc to hold the next hops to be returned. The size parameter in open_buffdesc must be set to indicate the amount of storage allocated. Upon return, the size parameter is set to specify the number of bytes actually written, while the numNextHops field in the route is set to specify the number of next hops. When the same open_buffdesc is used for output storage in making subsequent API calls, it is important to set the size parameter back to the allocated storage size.

Forwarding Table Change Notification

RPPI acts as a proxy for applications that want to be notified when the forwarding table changes. RPPI provides an RPC API, openapiBestRouteEventRegister(), that allows an application to register for best route changes. The application identifies itself by name. RPPI returns a unique client ID. RPPI can accept up to 16 registrations. If RPPI receives a registration request with the same name as an existing registration, RPPI replaces the existing registration.

RPPI sends best route change event messages to an application address formed from the client ID:

/tmp/rppi_brc.<client-ID>

To gracefully deregister for forwarding table changes, an application calls an RPC API, openapiBestRouteEventDeregister(), with its client ID and then deletes its socket.

When the forwarding table changes, RPPI forwards the notification to each application by sending a message over the application's UNIX socket. The message send is done on an RPPI thread. The notification message has the following format:

        0                   1                   2                   3
        0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |   Message Type                |         Message Length        |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                          Client ID                            |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

An application should ignore messages with any other message type received over this socket.

Upon receipt of this message, the application invokes the route change request RPC API, passing its client ID to identify itself. In response to this call, RPPI returns the next forwarding table change pending for the application (as identified by the application's client ID). When the RPC call returns, if a route was returned, the application invokes the RPC call again. This cycle repeats until the RPC call does not return a route, thus indicating no additional forwarding table changes are pending.

Maintaining a forwarding table change list for a client can use significant memory. When RPPI sends a best route change notification message to an application or responds to a get RPC call with a non-NULL route, RPPI starts a 10-second timer. If the application does not invoke the RPC call to retrieve the next change before the timer expires, RPPI deregisters the client, frees the client's change list and stops sending KEEPALIVE messages to the client.

When an application registers for forwarding table changes, ICOS puts every route in the forwarding table on a change list for the application and immediately notifies the application that changes are pending. The application retrieves these changes to get a baseline of routes. If at some later time an application wants to get a complete list of current routes, it can use the RPC API openapiBestRouteNextGet().