Merge pull request #13332 from LabNConsulting/chopps/new-opts

[mirror_frr.git] / doc / developer / ospf-api.rst

OSPF API Documentation
======================

Disclaimer
----------

The OSPF daemon contains an API for application access to the LSA database.
This API and documentation was created by Ralph Keller, originally as patch for
Zebra. Unfortunately, the page containing documentation for the API is no
longer online. This page is an attempt to recreate documentation for the API
(with lots of help from the WayBackMachine).

Ralph has kindly licensed this documentation under GPLv2+. Please preserve the
acknowledgements at the bottom of this document.

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 FRRouting (forked from Quagga and 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).

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.

.. figure:: ../figures/ospf_api_architecture.png
   :alt: image

   image

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.

One of the main objectives of the implementation is to make as little changes
to the existing Zebra code as possible.

Installation & Configuration
----------------------------

Download FRRouting and unpack it.

Configure and build FRR (note that ``--enable-opaque-lsa`` also enables the
ospfapi server and ospfclient).

::

    % sh ./configure --enable-opaque-lsa
    % make

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 :file:`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!

Usage
-----

In the following we describe how you can use the sample application to
originate opaque LSAs. The sample application first registers with the OSPF
daemon the opaque type it wants to inject and then waits until the OSPF daemon
is ready to accept opaque LSAs of that type. Then the client application
originates an opaque LSA, waits 10 seconds and then updates the opaque LSA with
new opaque data. After another 20 seconds, the client application deletes the
opaque LSA from the LSDB. If the clients terminates unexpectedly, the OSPF API
module will remove all the opaque LSAs that the application registered. Since
the opaque LSAs are flooded to other routers, we will see the opaque LSAs in
all routers according to the flooding scope of the opaque LSA.

We have a very simple demo setup, just two routers connected with an ATM
point-to-point link. Start the modified OSPF daemons on two adjacent routers.
First run on msr2:

.. code-block:: console

   # ./ospfd --apiserver -f /usr/local/etc/ospfd.conf

And on the neighboring router msr3:

.. code-block:: console

   # ./ospfd --apiserver -f /usr/local/etc/ospfd.conf

Now the two routers form adjacency and start exchanging their databases.
Looking at the OSPF daemon of msr2 (or msr3), you see this:

.. code-block:: console

   ospfd> show ip ospf database

          OSPF Router with ID (10.0.0.1)

                   Router Link States (Area 0.0.0.1)

   Link ID         ADV Router      Age  Seq#       CkSum  Link count
   10.0.0.1        10.0.0.1          55 0x80000003 0xc62f 2
   10.0.0.2        10.0.0.2          55 0x80000003 0xe3e4 3

                   Net Link States (Area 0.0.0.1)

   Link ID         ADV Router      Age  Seq#       CkSum
   10.0.0.2        10.0.0.2          60 0x80000001 0x5fcb

Now we start the sample main application that originates an opaque LSA.

.. code-block:: console

   # cd ospfapi/apiclient
   # ./main msr2 10 250 20 0.0.0.0 0.0.0.1

This originates an opaque LSA of type 10 (area local), with opaque type 250
(experimental), opaque id of 20 (chosen arbitrarily), interface address 0.0.0.0
(which is used only for opaque LSAs type 9), and area 0.0.0.1

Again looking at the OSPF database you see:

.. code-block:: console

   ospfd> show ip ospf database

          OSPF Router with ID (10.0.0.1)

                   Router Link States (Area 0.0.0.1)

   Link ID         ADV Router      Age  Seq#       CkSum  Link count
   10.0.0.1        10.0.0.1         437 0x80000003 0xc62f 2
   10.0.0.2        10.0.0.2         437 0x80000003 0xe3e4 3

                   Net Link States (Area 0.0.0.1)

   Link ID         ADV Router      Age  Seq#       CkSum
   10.0.0.2        10.0.0.2         442 0x80000001 0x5fcb

                   Area-Local Opaque-LSA (Area 0.0.0.1)

   Opaque-Type/Id  ADV Router      Age  Seq#       CkSum
   250.0.0.20      10.0.0.1           0 0x80000001 0x58a6  <=== opaque LSA

You can take a closer look at this opaque LSA:

.. code-block:: console

   ospfd> show ip ospf database opaque-area

          OSPF Router with ID (10.0.0.1)


                   Area-Local Opaque-LSA (Area 0.0.0.1)

   LS age: 4
   Options: 66
   LS Type: Area-Local Opaque-LSA
   Link State ID: 250.0.0.20 (Area-Local Opaque-Type/ID)
   Advertising Router: 10.0.0.1
   LS Seq Number: 80000001
   Checksum: 0x58a6
   Length: 24
   Opaque-Type 250 (Private/Experimental)
   Opaque-ID 0x14
   Opaque-Info: 4 octets of data
   Added using OSPF API: 4 octets of opaque data
   Opaque data: 1 0 0 0 <==== counter is 1

Note that the main application updates the opaque LSA after 10 seconds, then it
looks as follows:

.. code-block:: console

   ospfd> show ip ospf database opaque-area

          OSPF Router with ID (10.0.0.1)


                   Area-Local Opaque-LSA (Area 0.0.0.1)

   LS age: 1
   Options: 66
   LS Type: Area-Local Opaque-LSA
   Link State ID: 250.0.0.20 (Area-Local Opaque-Type/ID)
   Advertising Router: 10.0.0.1
   LS Seq Number: 80000002
   Checksum: 0x59a3
   Length: 24
   Opaque-Type 250 (Private/Experimental)
   Opaque-ID   0x14
   Opaque-Info: 4 octets of data
   Added using OSPF API: 4 octets of opaque data
   Opaque data: 2 0 0 0  <==== counter is now 2

Note that the payload of the opaque LSA has changed as you can see above.

Then, again after another 20 seconds, the opaque LSA is flushed from the LSDB.

Important note:
^^^^^^^^^^^^^^^

In order to originate an opaque LSA, there must be at least one active
opaque-capable neighbor. Thus, you cannot originate opaque LSAs if no neighbors
are present. If you try to originate when no neighbors are ready, you will
receive a not ready error message. The reason for this restriction is that it
might be possible that some routers have an identical opaque LSA from a
previous origination in their LSDB that unfortunately could not be flushed due
to a crash, and now if the router comes up again and starts originating a new
opaque LSA, the new opaque LSA is considered older since it has a lower
sequence number and is ignored by other routers (that consider the stalled
opaque LSA as more recent). However, if the originating router first
synchronizes the database before originating opaque LSAs, it will detect the
older opaque LSA and can flush it first.

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:

.. figure:: ../figures/ospf_api_msghdr.png
   :alt: image

   image

The message type field can take one of the following values:

+-------------------------------+---------+
| Messages to OSPF daemon       | 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 daemon   | 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:

.. figure:: ../figures/ospf_api_msgs1.png
   :alt: image

   image

The origin field allows origin-based filtering using the following origin
types:

+-------------------------+---------+
| Origin                  | Value   |
+=========================+=========+
| NON\_SELF\_ORIGINATED   | 0       |
+-------------------------+---------+
| SELF\_ORIGINATED        | 1       |
+-------------------------+---------+
| ANY\_ORIGIN             | 2       |
+-------------------------+---------+

The reply message has one 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:

.. figure:: ../figures/ospf_api_msgs2.png
   :alt: image

   image


.. Do not delete these acknowledgements!

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.