A gRPC Network Management Interface (gNMI) is a gRPC based protocol that defines a service or set of services or RPC methods used to configure and retrieve data from network devices.
The SR Linux provides a gNMI-based RPC for the modification and retrieval of a configuration. Supported RPCs are:
When the SR Linux gNMI process communicates data to a client, it uses common notification messages. Notification messages use the fields shown in Table 6.
Field | Definition |
timestamp | Time data was collected |
prefix | Prefix applied to all path fields included in the notification message. The paths expressed within the message are formed by the concatenation of prefix + path. |
update | List of update messages that indicate changes in the underlying data. Subfields are:
|
delete | List of paths indicating the deletion of data nodes |
Timestamp values are represented in nanoseconds. The value is encoded as a signed 64-bit integer (int64).
A prefix can be specified to reduce the lengths of path fields within a message. The absolute path is a concatenation of the path elements representing the prefix and the list of path elements in the path field. For example:
Paths are represented according to gNMI path conventions. Each path is represented by an ordered list of PathElem messages, starting at the root node, and ending at the most specific path element (versus a single string with a “/” character separating each element). Each PathElem message contains the name of the node within the data tree, along with any associated keys and attributes that may be required. For example:
Multiple paths are supported. Multiple notification messages are triggered in response to each path. For example:
The value of a data node can be the following:
When structured data is sent in an update message, it is serialized according to supported encoding, as shown in Table 7.
Data type | Description | Field |
ASCII | An ASCII encoded string | ascii_val |
JSON_IETF | A JSON encoded string using JSON encoding compatible with RFC 7951 | json_ietf_val |
The get RPC lets you obtain a view of the existing state. A GetRequest message is sent to the target (SR Linux gNMI process gnmi_mgr) that specifies the data to retrieve. A GetResponse message is returned that reflects the values of specified leafs at the collection time.
The get RPC is recommended for retrieving small data sets. For larger data sets, the gNMI subscribe RPC is recommended, using the ONCE mode.
A GetRequest message retrieves a view of data from the server. A Get RPC requests the server retrieve a subset of the data tree as specified by the paths included in the message and serializes this using the specified encoding.The GetRequest message uses the fields shown in Table 8.
Field | Definition |
path | Path (or set of paths) for the requested data view. Wildcards are permitted. |
type | Type of data requested. Supported options are:
|
encoding | Encoding that the target should use (ASCII or JSON_IETF). If not specified, JSON is the default. |
extension | Repeated field to carry gNMI extensions |
The GetResponse message uses the fields shown in Table 9.
Field | Definition |
notification | Set of notification messages for each path specified in the GetRequest; see Common notification messages for definitions of common messages. |
extension | Repeated field to carry gNMI extensions |
The set RPC lets you modify an existing state. A SetRequest message is sent to the target (SR Linux gNMI process gnmi_mgr) that specifies the required modifications. The server deletes, replaces, and updates paths based on the order they are listed. For each operation designated in the SetRequest message, an UpdateResult message is included in the SetResponse message.
The SetRequest message uses the fields shown in Table 10.
Field | Definition |
prefix | A specified prefix is applied to all defined paths within each field |
delete | A set of paths to be removed from the data tree |
replace | A set of update messages that defines content to replace |
update | A set of update messages that defines content to update |
extension | Repeated field to carry gNMI extensions |
An update message indicates changes to paths where a new value is required. Update messages contain the following:
All changes to the state included in a SetRequest message are consider part of a transaction. Either all modifications are applied or changes are rolled back to reflect the original state. For changes to be applied together, they must be in a single SetRequest message.
For replace operations, the behavior of omitted data elements depends on whether they are non-default values (set by a previous SetRequest message) or unmodified defaults. When the replace operation omits values that have been previously set, they are deleted from the data tree. Otherwise, omitted data elements are created with their default values.
For update operations, only the value of the data elements explicitly specified are changed.
The SetResponse message uses the fields shown in Table 11.
Field | Definition |
prefix | The prefix specified for all paths |
response | A list of responses (one per operation). Each response consists of an UpdateResult message with the following:
|
extension | Repeated field to carry gNMI extensions |
The subscribe RPC lets you receive updates relating to the state of data instances. The user creates a subscription using the subscribe RPC with the desired subscription mode. The defined mode triggers how and when the data is sent to the client.
A SubscribeRequest message is sent to the target (SR Linux gNMI process gnmi_mgr) to request updates for one or more paths. A SubscribeReponse message is sent to the client over an established RPC.
The SubscribeRequest message uses the fields shown in Table 12.
Field | Definition |
subscribe | A SubscriptionList message specifying a new set of paths to subscribe to |
extension | Repeated field to carry gNMI extensions |
Subscriptions are set once and cannot be modified. A new subscribe RPC call must be created for new paths. To end an existing subscription, the client must cancel the subscribe RPC that relates to the subscription.
A SubscriptionList message indicates a set of paths where common subscription behavior is required. The SubscriptionList message uses the fields shown in Table 13.
Field | Definition |
subscription | A set of subscription messages indicating the paths associated with the subscription |
mode | Type of subscription to create:
|
extension | Repeated field to carry gNMI extensions |
ONCE subscriptions are one-time requests. A ONCE subscription is created by sending a SubscribeRequest message with the subscribe field containing a SubscriptionList, with the mode type set to ONCE. The relevant update messages are sent and the RPC channel is closed.
STEAM subscriptions are long-lived and transmit updates indefinitely. A STREAM subscription is created by sending a SubscribeRequest message with the subscribe field containing a SubscriptionList, with the mode type set to STREAM. The STEAM mode subscription message also specifies a mode.
The SubscribeResponse message uses the fields shown in Table 14.
Field | Definition |
update OR sync_response | A response field. Only one type can be specified per message:
|
extension | Repeated field to carry gNMI extensions |
The capabilities RPC lets you discover the capabilities of a specific gNMI server.
A CapabilityRequest message is sent by the client to request capability information from the target. The target replies with a CapabilityResponse message that includes its gNMI service version, the versioned data models it supports, and the supported data encodings.
This information is used in subsequent RPC messages from the client to indicate the set of models that the client will use, and the encoding used for data.
The CapabilityRequest message is sent by the client to request capability information from the target. The CapabilityRequest message carries a single repeated extension field which can be used to carry gNMI extensions.
A CapabilityResponse message is sent from the target and includes the following fields:
The gNMI uses its own private candidate that allows multiple users or services to make simultaneous changes to a configuration.
Open source clients can be used to run GetRequests, SetRequests, subscriptions, and capabilities. The examples that follow show requests and responses using the following clients although any client that conforms to gNMI specifications can be used:
The get gNMI-RPC lets you retrieve state and configuration from a datastore. The following examples are shown:
Example 1: get all request
Example 2: get all response
Example 3: get interface with wildcard key request
Example 4: get interface with wildcard key response
The set gNMI-RPC lets you modify the state. The following examples are shown:
Example 1: set a delete request
Example 2: set a delete response
Example 3: set a update all request
Example 4: set a update all response
The cli gNMI-RPC lets you subscribe and receive updates on the state of a data instance. The following examples are shown:
In these examples, -qt specifies the subscription type. ONCE mode is the default and therefore is not shown in the first example.
Example 1: Subscribe ONCE for all request
Example 2: Subscribe ONCE for all response
Example 3: Subscribe STREAM ON_CHANGE interface request
Example 4: Subscribe STREAM ON_CHANGE interface response
The capabilities gNMI-RPC lets you discover the capabilities of a specific gNMI server. The following example is shown:
Example 1: Request server capabilities for specified server
Example 2: Response to a server capabilities request