Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

gRIBI

SUMMARY gRPC Routing Information Base Interface (gRIBI) is a gRPC service that enables external applications to programmatically add, modify, and remove routes on a network device.

The gRIBI service is an API for adding, modifying, and removing routing entries in a device's routing information base (RIB, also known as a routing table). If the entry is eligible for forwarding, the operating system automatically adds the entry to the device's forwarding information base (FIB, also known as a forwarding table). gRIBI client applications can use any language supported by the Juniper Extension Toolkit (JET). The client application can run on an external network management system or as a local application on the network device.

The gRIBI service proto defintion file is located at https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto. The gRIBI messages that are supported by Junos devices are located in the JET IDL package.

The OpenConfig Abstract Forwarding Table (AFT) model is a YANG data model that describes the forwarding entries installed on a network device. gRIBI uses a Protocol Buffer translated version of the OpenConfig AFT model to describe the RIB entries that it can modify. The protobuf representation of the OpenConfig AFT schema is in the proto definition file located at https://github.com/openconfig/gribi/blob/master/v1/proto/gribi_aft/gribi_aft.proto.

Benefits of gRIBI:

  • Sends acknowledgments when you program a route.
  • Supports hierarchical lookups.
  • Supports arbitration when multiple clients are connected to the gRIBI session.

Use the show route extensive command to display route data for gRIBI including the client ID and the next hop group ID used by the route.

Note:

We recommend using either gRIBI or the JET RIB Service API, not both simultaneously, especially for same set of routes.

Supported RPCs

Junos devices support gRIBI service RPCs to remotely retrieve, add, modify, or delete routes from a device's RIB. The RPCs function by modifying or reading the abstract forwarding tables (AFTs) on the device.

Table 1: Supported gribi.proto RPCs
RPC Definition Introduced in Release
Modify()

Add, modify, or delete entries from the AFT.

Junos OS Release 19.4R1

Junos OS Evolved Release 20.3R1
Get()

Retrieve the installed entries from the AFT.

Junos OS Evolved 22.2R1
Flush()

Remove all the device's AFT entries that match what is described in the FlushRequest message.

Junos OS Evolved 22.2R1

Network Device Configuration

Junos OS Evolved Release 23.4R1 and Later

Before you begin:

To configure the network device for gRIBI:

  1. Create a routing instance with filter-based forwarding.
  2. Configure the two policies: one to handle multipath resolve and one to handle load balancing.

    In this example, a policy called mp-resolve handles multipath resolve. If the resolving route has multiple paths, the resolved route resolves over all the paths. The policy pplb tells the Packet Forwarding Engine to load balance the traffic for each packet.

  3. Set the remnant holdtime to give the system enough time to update the routes. After the system restarts, the rpd process waits until the remnant holdtime expires before cleaning up the routes. The rpd process does not delete any routes that are updated before the wait time expires.

    You are now ready to use gRIBI service RPCs.

Before Junos OS Evolved Release 23.4R1

Before you begin:

To configure the network device for gRIBI:

  1. Create a routing instance with filter-based forwarding.
  2. Configure the routing table(s) you want to use for default, IPv4 family protocol, and IPv6 family protocol route resolution in your routing instance.

    You can specify up to two routing tables for each protocol family. The route resolution scheme only checks the second routing table if it can't find an entry for the protocol next-hop address in the first routing table.

    In this example, the teVRF.inet.0 is the default routing table. If there is no route for the next-hop address in that routing table, the route solution scheme checks the inet.3 table.

  3. Specify import policies for the IPv4 and IPv6 family resolution trees.

    For example:

  4. Configure the two policies: one to handle multipath resolve and one to handle load balancing.

    In this example, a policy called mp-resolve handles multipath resolve. If the resolving route has multiple paths, the resolved route resolves over all the paths. The policy pplb tells the Packet Forwarding Engine to load balance the traffic for each packet.

  5. Configure the routing options to preserve the next hop hierarchy when installing a next hop in the forwarding plane.
  6. Configure the routing table(s) you want to use for IPv4 and IPv6 family protocol route resolution and the policy for route resolution at the routing options level. Repeat this configuration for each routing table you configured at the routing instance level.

    For example:

  7. Set the remnant holdtime to give the system enough time to update the routes. After the system restarts, the rpd process waits until the remnant holdtime expires before cleaning up the routes. The rpd process does not delete any routes that are updated before the wait time expires.

    You are now ready to use gRIBI service RPCs.

Modify Routes

Use the Modify() RPC to install new routes and edit existing routes in the gRIBI server's RIB. Routes are added as static routes.

Modify() is a bidirectional streaming RPC. The client sends a Modify() RPC containing ModifyRequest messages to modify an AFT entry on the server. For each ModifyRequest, the gRIBI server responds to the client with a ModifyResponse message.

The ModifyRequest message comprises one or more AFTOperation messages. Each AFTOperation message defines a request to add, modify, or remove a single AFT entry. The gRIBI server processes the AFT operations in the order that the Modify() RPC streams them.

Junos devices support the following AFT entry types:

  • IPv4Entry—Program an IPv4 route.
  • NextHopEntry—Program a next hop.
  • NextHopGroup—Program a next hop group.

Use the Modify() RPC to perform the following functions:

Route Acknowledgments

The server sends an acknowledgment when you successfully program a route in the Packet Forwarding Engine using the Modify() RPC. If the gRIBI API fails to program a route in the Packet Forwarding Engine within the given timeout period, the server sends an error message. You can configure the length of this timeout. The acknowledgment is only valid for the most recent route. If an older route sends an acknowledgment but the new route does not, the Packet Forwarding Engine records it as an error.

Junos devices support the following values in the entry field of the message AFTOperation:

Note:

Junos devices do not support the MAC_ENTRY option.

Use the show route extensive command to display the acknowledgment status. The acknowledgment status is persistent across rpd process restarts.

Program an IPv4 Route

To program an IPv4 route, use the IPv4Entry AFT entry. The AFT matches the input packets based on the destination address and maps them to the corresponding next hops. Install the AFT entry on the default VRF instance as well as the traffic engineering VRF instances in your network. To install an AFT entry in a non-default instance, specify the VRF instance in the network_instance field of the AFTOperation message. For example:

  • Traffic engineering VRF instance: g_b4_cos1
  • Set the network_instance field to: g_b4_cos1

The gRIBI client only programs the IPv4Entry AFT entry on the server after it receives acknowledgments from the server that the server received the associated NextHopGroup and NextHop messages. If the client programs the IPv4Entry AFT entry on the server without acknowledgment of the NextHopGroup message, it adds the route to the server as a hidden route.

Program Next Hops and Next Hop Groups

Use the gRIBI Modify() RPC to program a next hop or a next hop group on the gRIBI server. The RPC only creates next hops and next hop groups within the default VRF instance.

When there are next hops and next hop groups in the same ModifyRequest message, the gRIBI client handles them according to the AFT operation. If the AFT operation adds NextHop and NextHopGroup entries, the client adds all the next hops to the server before adding the next hop groups. If the AFT operation deletes NextHop and NextHopGroup entries, the client processes them in the reverse order: it deletes all the next hop groups before deleting the next hops.

In Junos devices, the RPC instantiates next hops in the inet6.3 table as FC01::next_hop_id, where the next hop ID is in hexadecimal. For example, if the next hop ID is 10, the server installs a route called FC01::A in the inet6.3 table.

Next hop groups appear in the inet6.3 table as FC02::next_hop_id. For example, if the next hop group ID is 100, the server installs a route called FC02::64 in the inet6.3 table.

For example, to program a next hop object via a directly reachable interface:

  1. Assuming the address 10.0.1.2 is reachable via interface et-0/0/7.0, set the following fields in the Afts message, where = means set the field to that value:

  2. Set the AFTOperation message fields as follows:

  3. Set the ModifyRequest message to use the AFTOperation defined above.

  4. Call the Modify() RPC with the above ModifyRequest message.

  5. To confirm the route was programmed successfully, use the show route programmed command in the CLI.

Program Next Hops with MAC Addresses

Optionally, you can identify a next hop with its MAC address instead of its IP address. This feature is useful in networks where devices cannot use dynamic Address Resolution Protocol (ARP) or Neighbor Discovery Protocol (NDP) to look up the next hop's MAC address. To use the MAC address, use the mac_address field instead of the ip_address field in the AFT message.

Note: All traffic using this interface uses the static MAC address programmed by the gRIBI service, even traffic on routes not programed by the gRIBI service.

After you use the gRIBI service to program a MAC address as the next hop on the interface, the device does not use dynamic ARP or NDP for any traffic using this interface. If the programmed gRIBI next hop is deleted or purged when the client disconnects, the device automatically re-enables ARP on the interface and the route continues to function using dynamic ARP.

For example, to program a next hop object with a MAC address via a directly reachable interface:

  1. Make sure the interface you want to program with a next hop is a numbered interface.

  2. Make sure the IPv6 family is enabled on the interface.

  3. Assuming the MAC address 00:00:5E:00:53:00 is reachable via interface et-0/0/7.0, set the following fields in the Afts message, where = means set the field to that value:

  4. Set the AFTOperation message fields as follows:

  5. Set the ModifyRequest message to use the AFTOperation defined above.

  6. Call the Modify() RPC with the above ModifyRequest message.

  7. To confirm the route was programmed successfully, use the show route programmed command in the CLI.

Hierarchical Lookups and IP-in-IP Tunneling

The Junos implementation of gRIBI supports hierarchical lookups. To configure hierarchical lookups, use the IPv4 AFT to program IP-IP tunnel endpoints and site group virtual IP address routes.

To encapsulate traffic on the ingress node in an IP-in-IP tunnel, set the following fields in the NextHop message:

Arbitration for Multiple Clients

The Modify() RPC supports arbitration when multiple clients are connected to the gRIBI server. Arbitration determines which client can perform which operations.

Use the SessionParameters message to set the persistence mode and the client redundancy mode for the gRIBI clients. All clients must send the same values of all the attributes of the SessionParameters message. SessionParameters should be sent only once during the lifetime of the session.

SessionParameters must be the first message sent after a reconnect. When a client reconnects, a new session starts. If other clients are already connected, match the SessionParameters message values to the values set by existing clients. If all the clients reconnect, you can set the SessionParameters message values to different values than the ones used in the previous session.

Junos devices support both PRESERVE and DELETE persistence modes. If the persistence mode is set to PRESERVE, then the server preserves the AFT entries added by the client even after the client disconnects. If the persistence mode is set to DELETE, then the server deletes the AFT entries when the client disconnects.

We recommend deleting all routes before changing session parameters. You might see unexpected behavior if you change the session parameters and switch the redundancy mode between ALL_PRIMARY and SINGLE_PRIMARY after adding routes in the other mode.

When there are multiple clients, you must chose between two client redundancy modes:

All Primary Mode

In ALL_PRIMARY redundancy mode:

  • Any client can modify routes.

  • Multiple clients can add the same AFT entry.

  • The gRIBI API maintains a mapping of which clients have added the route.

  • The first add operation adds the entry to the RIB. Subsequent add operations for the same entry from a different client adds the client to the list of clients referencing the entry.

  • Delete operations remove the client from the list of clients referencing the entry. The entry is only deleted when there are no clients referencing the entry.

Note:

When FlushRequest is processed, the entries are deleted without any reference count checks.

Use the show route extensive command to view the details of the route. Here is an example of what the show route extensive command displays in ALL_PRIMARY mode. The output has been shortened for clarity.

Single Primary Mode

In SINGLE_PRIMARY redundancy mode:

  • gRIBI clients can have a primary (active) or backup role.

  • Only the primary client can perform AFT operations.

  • The client with the highest election ID is the primary client. All other clients are backup clients.

  • When a backup client becomes the primary client, the routes added by the previous primary client can be modified by the new primary client.

Set the election ID for each device to determine which client is the primary client. You can only set the election ID in SINGLE_PRIMARY redundancy mode. The election ID is preserved even if a client is in the down state. If the primary client disconnects, it remains the primary client until you set the election ID of another device to be higher. After the election ID is set, the new primary client continues programming the gRIBI entries.

To update the election ID, send the ModifyRequest message with the election ID set to its new value. Each client must have a unique election ID. Do not set any other fields of the ModifyRequest message when you update the election ID.

The election ID is present in the following messages:

  • ModifyRequest—Set the election ID for the client. The client with the highest election ID becomes the primary client.

  • AFTOperation—Determines if the server should process the AFT operation.

  • ModifyResponse—The server responds with the current highest election ID.

Use the show programmable-rpd clients detail command to view the group ID and whether the client has the primary or backup role.

Use the show route extensive command to view the details of the route. Here is an example of what the show route extensive command displays in SINGLE_PRIMARY mode. The output has been shortened for clarity.

Program a Fallback Route in a VRF Instance

When a next hop becomes unreachable through a static route, the network can reroute the traffic through an alternate route to avoid traffic disruption. This alternate route is called a fallback route. If the traffic was not encapsulated in a tunnel, configure the fallback static route as you usually would using the CLI. However, if the traffic was encapsulated in a tunnel, you can use gRIBI to program a fallback tunnel that includes decapsulation and encapsulation.

You can program the fallback route in the VRF so that the system decapsulates the traffic from the old tunnel and re-encapsulates it in a new tunnel before re-routing the traffic to the next hop. This feature supports IPv4 transport for dynamic IP-IP tunnels with an IPv4 or IPv6 payload.

To program a fallback IP-in-IP tunnel with decapsulation and re-encapsulation capability, set the following fields in the NextHop message:

You can use a default route in a traffic engineering virtual routing and forwarding (VRF) instance as the backup route. Add the default route to the VRF first so the future routes you configure in the VRF will use it as a fallback route. To use this default route, set the decapsulate_header field to OPENCONFIGAFTTYPESENCAPSULATION HEADERTYPE_IPV4 and set network_instance to DEFAULT. This default route has a next hop with decapsulation and looks up routes in the default VRF.

You can also select a backup next hop group to make it easier to configure a fallback route. To do so, set the backup_next_hop_group field in the NextHopGroup message.

VRF Instance Selection

gRIBI does not support programming routes in a non-default VRF instance. To use a non-default VRF instance, first configure a firewall filter using the CLI. The firewall filter must match the DSCP and IP protocol required. Apply the filter to the interface on which the traffic is expected.

For example, if traffic is on interface et-0/0/0:

Policy-Based Forwarding

Use the PolicyForwardingEntry message to program policy-based forwarding on the gRIBI server. Policy-based forwarding ensures that traffic moved to the backup tunnel remains in the tunnel regardless of what the routing table says.

To set the match conditions and program a policy for forwarding traffic:

  1. Set the following fields in the Afts message:

  2. Set the following fields in the AFTOperation message:

  3. Set the ModifyRequest message to use the AFTOperation defined above.

  4. Call the Modify() RPC with the above ModifyRequest message.

Get Routes

When the client loses the connection to the gRIBI server, any routes that were programmed during the downtime might not be added to the server. After the connection to the server comes back up, use the Get() RPC to check that all the routes were added correctly to the server's routing table. The Get() RPC is also useful for periodically checking that the routes installed on a server are correct and reconciling any differences.

The Get() RPC retrieves the contents of the AFTs installed on the server. When the client sends a Get() RPC request, the server responds with the set of currently installed entries using the GetResponse stream. The server only responds with the entries that have been acknowledged. After the server sends all the entries to the client, the server closes the RPC.

If graceful Routing Engine switchover (GRES) is configured, the gRIBI server and rpd process also recover routes after the gRIBI server restarts. After the client reconnects to the server, the client automatically sends a gRIBI Get() RPC request to the server. If GRES is configured, the client reconciles the routes on the server. If the client sends another Get() RPC request, the GetResponse stream includes the active reconciled routes on the server. If GRES is configured and non-stop routing is not configured, the gRIBI API also recovers routes after a Routing Engine switchover.

Note:

Only active routes are recovered when the rpd process restarts.

Flush Routes

The Flush() RPC removes all the server's gRIBI programmed routes that match what is described in the FlushRequest message. Sending a FlushRequest message is a quick and easy way to delete gRIBI programmed routes from the server.

When routes are present in a traffic engineering VRF instance, flush the routes from the VRF instance using the Flush() RPC before deleting the VRF instance.

Change History Table

Feature support is determined by the platform and release you are using. Use Feature Explorer to determine if a feature is supported on your platform.

Release
Description
change-completed