This RPPI service serves applications that require access to the ICOS router configuration and state, both global and per-interface. The service includes RPC APIs an application can call to get current routing configuration and state and events that RPPI sends to notify applications of changes.
Router Configuration and State APIs
This service includes RPC APIs to do the following:
- Query whether routing is globally enabled or disabled
- Iterate through the set of routing interfaces
- Get the interface type for a given interface
- Get the VLAN ID of a given interface (VLAN interfaces only)
- Get the loopback ID of a given interface (loopback interfaces only)
- Get an interface's name (e.g., "loopback 0", "vlan 10")
- Get the IP stack interface index of a given interface
- Query whether a given router interface is up or down
- Get the set of IP addresses on an interface
- Get the IP address method for a given interface
- Get the IP MTU of an interface
- Get the "bandwidth" of an interface
Router Events
Changes to router configuration and state are called router events. An application can register to receive router events using the following RPC API:
open_error_t openapiRouterEventRegister(OPEN_AF_t af, uint32_t pid, open_buffdesc *clientName, uint32_t *clientId);
The application calls the registration API once for each address family it is interested in. The RPC call returns a client ID as an output parameter. A separate API is provided to deregister from this service. After registering through the RPC API, the application opens a UNIX datagram socket and binds to /tmp/rppi_rec.<client-id>.
RPPI maintains a router event list for each address family (IPv4 and IPv6) per registered application.
When the routing configuration or state changes, RPPI sends a message over its UNIX socket to each registered application for the address family of the event. Router event messages have 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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Internal Interface Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Message Type indicates the type of router event. The router event type codes are listed below.
- Message Length is the total number of octets including Message Type and Message Length fields.
- Sequence Number is a monotonically increasing value that uniquely identifies an event
- Internal Interface Number is an unsigned, 32-bit integer that uniquely identifies an interface.
Applications can use RPC APIs to get the interface name, interface type, or IP stack interface index for a given internal interface number. The Internal Interface Number field is only included in messages for interface-specific events.
Router Event Type Codes
- 101 - IPv4 routing globally enabled. This event occurs after the global CLI configuration command, ip routing, is issued.
- 102 - IPv4 routing globally disabled. This event occurs after the global CLI configuration command, no ip routing, is issued.
- 103 - All IPv4 global and interface events have been generated after system initialization. When ICOS initializes after a reboot, it applies the system configuration. The system generates router events to indicate the initial state of each interface. This event indicates that the system configuration has been fully applied and the initial state of each interface is known and has been announced. An application that initializes before ICOS may wish to wait for this event before taking certain actions. The API openapiRoutingStartupStatus() can be queried at any time to determine whether routing initialization is complete.
- 106 - Routing interface IPv4 enable. IPv4 has become enabled on a given routing interface. Routing is only considered enabled on an interface if routing is enabled globally, the interface is up, the interface is configured for routing, and the interface has an IPv4 address.
- 108 - Routing interface IPv4 disable. IPv4 has been disabled on a given interface because one of the conditions for the routing interface to be up is no longer met.
- 110 - IPv4 address change. A secondary IPv4 address has been added or removed on the interface. The event message does not include the current set of IPv4 address on the interface. The application must use the RPC API, openapiRtrIntfIpAddrGet(), to retrieve the current set of addresses. This event is not sent when a primary IPv4 address is added or removed. When a primary address is added or removed, if the configuration change brings the interface up or down, a routing interface enable or disable event is sent.
- 111 - IPv4 MTU change. The event message does not include the current MTU value. An application that receives this event must call openapiIntfIpMtuGet() to get the current IP MTU.
- 112 - IPv4 interface bandwidth change. This is the interface "bandwidth" as configured with the bandwidth interface configuration CLI command. This bandwidth value may not be equivalent to the actual interface speed, particularly if the interface is a VLAN interface with multiple member ports, possibly with different interface speeds. This configured bandwidth value is commonly used to influence IGP interface cost.
- 113 - IPv4 is enabled as a non-forwarding interface. When IPv4 routing is not globally enabled, routing interfaces that meet all other conditions for being up are treated as non-forwarding host interfaces. This event indicates that an interface has been enabled in this mode.
- 115 - BFD session state changed from UP to DOWN, which implies destination is no longer reachable.
- 116 - BFD session state changed from DOWN to UP, which implies destination is reachable.
Acknowledging Router Events
Applications are required to acknowledge router events. If an application does not respond to an event within 10 seconds, RPPI deregisters the application for all address families and closes the application's socket, and responds to IP MAP as if the application had responded. An application acknowledges a router event by calling an RPC API:
open_error_t openapiRouterEventAcknowledge(uint32_t clientId, uint32_t eventId);
- clientId is the client ID provided in at registration,
- eventId is the Sequence Number from the event message
If an application deregisters while RPPI has outstanding events unacknowledged by the application, RPPI immediately considers the application to have acknowledged the outstanding events.
Querying Initial Routing Configuration and Status
An application only receives router events that occur after it has registered. To get a baseline of interface state, an application must first register for router events, then iterate through the current set of routing interfaces using the RPC API openapiRtrIntfNextGet(). For each routing interface, the application gets the current state and configuration using the other RPC APIs for interfaces.