About gRIBI

gRIBI (gRPC Routing Information Base Interface) is a gRPC-based protocol that allows external clients to inject routes into the RIB of a network device. The gRIBI clients add and remove RIB entries using a simple API that is defined by the gribi.proto. RIB entries are defined using the OpenConfig Abstract Forwarding Table (AFT) model, translated to protobuf (using ygot). The AFT model allows for a common vendor-independent abstraction of RIB information.

The protobuf definition of gRIBI is maintained in the gRIBI GitHub repository: gribi.proto. The corresponding gribi_aft.proto containing the OpenConfig AFT model is available in the same repository.

The fundamentals of the gRIBI interface are as follows:

The interface acts as a client of the routing table manager (fib_mgr) on the device.
Injected gRIBI entries can be interdependent on entries from other protocols, with the device handling resolution. (These entries are published in the RIB view of the system, which allows them to be observed using gNMI.)
The interface uses transactional semantics with a request/response design, such that the programming entity can determine the success or failure of an operation.
Rather than inject entries to appear as though they are coming from a particular protocol, gRIBI injects entries separately to live alongside the other existing protocols.
The gRIBI interface is normalised across vendors. Similar to OpenConfig, gNMI and gNOI, translation to vendor-specific data models is performed on the device, where it can be performed most effectively.
The interface is fundamentally considered to be part of the control plane of the device, not the management plane. Entries are created as though they are learned through a dynamic routing protocol, not as transient device configurations.

Supported RPCs

SR Linux supports the following gRIBI RPCs:

Modify RPC (ADD, DELETE, and REPLACE AFTOperations)
Get RPC
Flush RPC

Supported AFTs

SR Linux supports the following OpenConfig AFTs:

IPv4
Next-Hop Group
Next-Hop

Supported platforms

gRIBI is supported on the following hardware platforms:

7250 IXR-6
7250 IXR-10

Modify RPC

The Modify RPC is the primary gRIBI RPC, allowing gRIBI clients to add, modify, and remove entries in the RIB. The Modify RPC is a bidirectional streaming RPC that modifies the AFT using ModifyRequests. When the gRIBI server completes ModifyRequest operations, it responds (asynchronously) with one or more ModifyResponses indicating what actions were taken.

The structure of the Modify RPC is as follows:

rpc Modify(stream ModifyRequest) returns (stream ModifyResponse);

Ordering requirements

gRIBI clients must ensure the correct ordering of gRIBI transactions within ModifyRequests. Specifically, the clients must send next-hop and next-hop group entries before any IPv4 entry that depends on them. Clients send next hop groups and next hops as repeated AFTOperation messages in a single ModifyRequest. However, the clients must wait for the next-hop and next-hop group transactions to be acknowledged before proceeding to program the corresponding IPv4 entry.

To enforce the correct transaction ordering, the gRIBI server performs the following error handling:

If a next-hop group entry references a non-existent next-hop, then the programmed next-hop group is considered invalid and an error is returned to the client.
During deletion, if an entry to be deleted is still a dependency for another entry (for example, a next-hop that is still referenced from a next-hop group), an error is returned.

Redundancy and persistence session parameters

The gRIBI API allows multiple gRIBI clients to connect to the network device at once. To define how the network device interacts with the client sessions, the Modify RPC provides the following session parameters:

redundancy: defines whether the network device accepts entries from all clients or from a primary client only
persistence: defines whether AFT entries persist after a client disconnection

The first client to connect to the gRIBI server can set the redundancy and persistence parameters for all subsequent client connections. After the settings are defined, they cannot be altered until all clients have disconnected and all programmed entries are removed.

To define the session parameters, the client must send a ModifyRequest with the session_parameters field populated, but without any AFTOperations included.

Note: The client must send the session_parameters field before any AFTOperations. If a client sends a change to session parameters after a first-in AFTOperation, the gRIBI server ignores the change and returns an error.

The following table describes the available options for the sessions parameters.

Table 1. Session parameters options
Parameter	Options
redundancy	ALL_PRIMARY (Default) The network device accepts AFTOperations from all clients. However, when a client adds an entry, only that same client can modify or delete the entry. When the device receives the ADD AFTOperation from any client, it adds an AFT entry to its gRIBI state. But the device only deletes an AFT entry when it receives a DELETE operation from the client that previously issued the ADD for that entry. Similarly, the device processes REPLACE AFTOperations only for AFT entries that the client previously added. SINGLE_PRIMARY The network device accepts AFTOperations from the primary client only. In this case, the clients must take part in an election process (out of band of SR Linux) that identifies a single client as the primary client with the highest election ID.
persistence	DELETE (Default) When a client disconnects, the network device deletes all AFT entries received from that client (first IPv4Entry, then NextHopGroup, then NextHop). PRESERVE When the primary client disconnects (assuming SINGLE_PRIMARY redundancy), the network device preserves the routes programmed by the gRIBI server's RIB, the system RIB, and the system FIB. When a non primary client disconnects, no action is taken as all network element state is conveyed by the primary client. In this model, the gRIBI server builds state off of previously published information. This mechanism supports both a gRIBI server restart or a non-stop-forwarding failover to a standby CPM. Entries are not coupled to the liveliness of the Modify RPC. Entries persist until they are explicitly deleted, or the device performs a cold boot. Note: This is a deviation from the existing behavior expected in gRIBI.

Election ID

To handle scenarios where multiple clients consider themselves the primary client, each AFTOperation contains a new election ID. When the network device receives the election ID from the client, it compares the ID to the last known election ID. If the received election ID is less than the current election ID, it is ignored. If it is greater, the operation is accepted.

If the election ID is equal to the current ID, the client sending the update is accepted as the new primary client (in practice, this condition indicates a failure in the external primary election, but ensures a defined behavior for the device).

When the election ID in an AFTOperation does not match the current latest operation, an error is returned in the AFTResult indicating that the operation is not accepted.

Note: The gRPC session is not terminated in this case.

Get RPC

The Get RPC allows the client to retrieve the latest configuration from the network device. The client uses the Get RPC to retrieve the contents of the AFTs installed by the gRIBI server. The gRIBI server responds using a GetResponse stream containing the set of currently installed entries. When all entries are sent, the server closes the RPC.

The Get RPC is typically used for reconciliation between a client and a server after a disconnect or for periodic consistency checking.

The structure of the Get RPC is as follows:

rpc Get(GetRequest) returns (stream GetResponse);

Reconciliation

If a client becomes disconnected from the network device, it can reconcile the entries that are currently installed by the gRIBI server using the Get RPC.

The Get response returns the entries that the gRIBI server has installed on the device from any client. Only entries that have been acknowledged according to the defined per-session ACK requirement are returned to the gRIBI client; non-acknowledged entries are not sent. The client can use this information to identify the diff between the intended set of entries and the currently programmed set of entries and push the required updates.

An acknowledged entry is one for which the underlying ACK source (for example, hardware or RIB) has acknowledged the entry, instead of those for which an ACK was sent to a specific client. This addresses the case where a session failure occurs while an ACK is pending. Transmission of only acknowledged entries can result in a larger diff being sent by the client, but the intention of this mechanism is to ensure consistency at the end of the reconciliation process.

Application warm restart

Several events can occur on a device that can impact the liveliness of the gRIBI connection between the client and the network device. Particularly:

Where redundant control-planes exist, control-plane failure can cause a reconnection of the gRIBI Modify RPC
A gRIBI server restart on the device

In these cases, the device can determine the set of entries that were installed in gRIBI before the reconnection because these are programmed into the hardware persistently. After reconnection, the client can reconnect and perform a reconciliation.

After a warm restart, the gRIBI server behavior is as follows:

All clients are disconnected and need to start new sessions
Unreferenced next-hop entries are cleared (even if they were previously acknowledged in RIB_ACK mode)
If an interface reference (interface_ref ) was provided for a next-hop entry, it is not preserved after the restart
If metadata was provided for an IP entry, it is not preserved after the restart
If a next-hop within a next-hop-group has no weight, the weight value is set to 1 after the restart
The highest known election ID is reset to zero after the restart
Session parameters are cleared; the first client that connects after a warm restart can set the session parameters for all future clients

Flush RPC

The Flush RPC allows the client to remove all gRIBI routes from a specified network instance. This provides the client with a means to disable all gRIBI traffic engineering in case of system failure.

The client can send FlushRequests for specific network instances, and the network_instance is a mandatory field. The FlushRequest removes all installed AFT entries (IPv4Entry, NextHopGroup, and NextHop) in the specified network instance.

The FlushRequest also supports the option to flush all entries in all network instances.

The structure of the Flush RPC is as follows:

rpc Flush(FlushRequest) returns (FlushResponse);

Authentication

If the gRIBI server is not using UNIX sockets, sessions between the gRIBI client and SR Linux device must be encrypted using Transport Layer Security (TLS). Fall back to unencrypted sessions is not supported. You can specify TLS settings within a TLS profile and apply the TLS profile when configuring a gRIBI server within a network instance. When the gRIBI server is enabled, gRIBI clients connect and authenticate to the SR Linux device using the settings specified in the TLS profile.

With authenticate-client set to true in the TLS profile, new connections are mutually authenticated. Each entity validates the X.509 certificate of the remote entity to ensure that the remote entity is both known and authorized to connect to the local system.

See the "Using SPIFFE for client authentication (mTLS)" section in the SR Linux Configuration Basics Guide for information about using SPIFFE for client authentication in TLS sessions.

For details about setting up a TLS profile, see the SR Linux Configuration Basics guide.

Event Logging

You can configure logging of gRIBI information (username, operation) to syslog. Some RPCs produce a volume of logging information that can overwhelm the syslog, so you can disable or abbreviate logging on a per-RPC basis. For more information about configuring syslog, see the Logging chapter of the SR Linux Configuration Basics guide.