OSPF API
On this page... (hide)
1. Disclaimer
The OSPF daemon contains an API for application access to the LSA database. This API was created by Ralph Keller, originally as patch for Zebra. Some time ago the code has merged with Quagga. Unfortunately, the page containing documentation of the API is no longer online. This page is an attempt to recreate documentation for the API (with lots of help of the WayBackMachine)
2. Introduction
This page describes an API that allows external applications to access the link-state database (LSDB) of the OSPF daemon. The implementation is based on the OSPF code from the Quagga (formerly Zebra) routing protocol suite and is subject to the GNU General Public License. The OSPF API provides you with the following functionality:
- Retrieval of the full or partial link-state database of the OSPF daemon. This allows applications to obtain an exact copy of the LSDB including router LSAs, network LSAs and so on. Whenever a new LSA arrives at the OSPF daemon, the API module immediately informs the application by sending a message. This way, the application is always synchronized with the LSDB of the OSPF daemon.
- Origination of own opaque LSAs (of type 9, 10, or 11) which are then distributed transparently to other routers within the flooding scope and received by other applications through the OSPF API.
Opaque LSAs, which are described in RFC 2370 , allow you to distribute application-specific information within a network using the OSPF protocol. The information contained in opaque LSAs is transparent for the routing process but it can be processed by other modules such as traffic engineering (e.g., MPLS-TE).
3. Architecture
The following picture depicts the architecture of the Quagga/Zebra protocol suite. The OSPF daemon is extended with opaque LSA capabilities and an API for external applications. The OSPF core module executes the OSPF protocol by discovering neighbors and exchanging neighbor state. The opaque module, implemented by Masahiko Endo, provides functions to exchange opaque LSAs between routers. Opaque LSAs can be generated by several modules such as the MPLS-TE module or the API server module. These modules then invoke the opaque module to flood their data to neighbors within the flooding scope.
The client, which is an application potentially running on a different node than the OSPF daemon, links against the OSPF API client library. This client library establishes a socket connection with the API server module of the OSPF daemon and uses this connection to retrieve LSAs and originate opaque LSAs.
The OSPF API server module works like any other internal opaque module (such as the MPLS-TE module), but listens to connections from external applications that want to communicate with the OSPF daemon. The API server module can handle multiple clients concurrently.
( Picture is unfortunately missing )
One of the main objectives of the implementation is to make as little changes to the existing Zebra code as possible.
4. Installation & Configuration
Download Quagga and unpack
Configure your quagga version (note that --enable-opaque-lsa also enables the ospfapi server and ospfclient).
% sh ./configure --enable-opaque-lsa % gmake
This should also compile the client library and sample application in ospfclient.
Make sure that you have enabled opaque LSAs in your configuration. Add the ospf opaque-lsa statement to your ospfd.conf:
! -*- ospf -*- ! ! OSPFd sample configuration file ! ! hostname xxxxx password xxxxx router ospf router-id 10.0.0.1 network 10.0.0.1/24 area 1 neighbor 10.0.0.2 network 10.0.1.2/24 area 1 neighbor 10.0.1.1 ospf opaque-lsa <============ add this statement!
5. Protocol and Message Formats
If you are developing your own client application and you don't want to make use of the client library (due to the GNU license restriction or whatever reason), you can implement your own client-side message handling. The OSPF API uses two connections between the client and the OSPF API server: One connection is used for a synchronous request /reply protocol and another connection is used for asynchronous notifications (e.g., LSA update, neighbor status change).
Each message begins with the following header:
The message type field can take one of the following values:
| Messages to OSPF deamon | Value |
|---|---|
| MSG_REGISTER_OPAQUETYPE | 1 |
| MSG_UNREGISTER_OPAQUETYPE | 2 |
| MSG_REGISTER_EVENT | 3 |
| MSG_SYNC_LSDB | 4 |
| MSG_ORIGINATE_REQUEST | 5 |
| MSG_DELETE_REQUEST | 6 |
| Messages from OSPF deamon | Value |
|---|---|
| MSG_REPLY | 10 |
| MSG_READY_NOTIFY | 11 |
| MSG_LSA_UPDATE_NOTIFY | 12 |
| MSG_LSA_DELETE_NOTIFY | 13 |
| MSG_NEW_IF | 14 |
| MSG_DEL_IF | 15 |
| MSG_ISM_CHANGE | 16 |
| MSG_NSM_CHANGE | 17 |
The synchronous requests and replies have the following message formats:
The origin field allows to select according to the following types of origins:
| Origin | Value |
|---|---|
| NON_SELF_ORIGINATED | 0 |
| SELF_ORIGINATED | 1 |
| ANY_ORIGIN | 2 |
The reply message has on of the following error codes
| Error code | Value |
|---|---|
| API_OK | 0 |
| API_NOSUCHINTERFACE | -1 |
| API_NOSUCHAREA | -2 |
| API_NOSUCHLSA | -3 |
| API_ILLEGALSATYPE | -4 |
| API_ILLEGALOPAQUETYPE | -5 |
| API_OPAQUETYPEINUSE | -6 |
| API_NOMEMORY | -7 |
| API_ERROR | -99 |
| API_UNDEF | -100 |
The asynchronous notifications have the following message formats:
6. Original Acknowledgments from Ralph Keller
I would like to thank Masahiko Endo, the author of the opaque LSA extension module, for his great support. His wonderful ASCII graphs explaining the internal workings of this code, and his invaluable input proved to be crucial in designing a useful API for accessing the link state database of the OSPF daemon. Once, he even decided to take the plane from Tokyo to Zurich so that we could actually meet and have face-to-face discussions, which was a lot of fun. Clearly, without Masahiko no API would ever be completed. I also would like to thank Daniel Bauer who wrote an opaque LSA implementation too and was willing to test the OSPF API code in one of his projects.