gNMI

Common notification messages

When the SR Linux gNMI process communicates data to a client, it uses common notification messages. Notification messages use the fields shown in the following table.

Table 1. Common notification fields
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: path val (value)
delete	List of paths indicating the deletion of data nodes

Timestamps

Timestamp values are represented in nanoseconds. The value is encoded as a signed 64-bit integer (int64).

Path prefix

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:

Path Prefix

notification: <
timestamp: (timestamp) // timestamp as int64
prefix: <
  elem: <
      name: "a"
    >
  elem: <
     name: "b"
     key: <
        key: "name"
        value: "b1"
       >
     >
  elem: <
     name: "c"
  >
>
update: <
  path: <
    elem: <
      name: "d"
    >
  >
  value: <
    val: <
      json_val: "AStringValue"
    >
  >
>
update: <
  path: <
    elem: <
      name: "e"
    >
  >
  val: <
    json_val: 10042 // converted to int representation
  >
 >
>

Paths

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:

path: <
  elem: <
    name: "a"
  >
  elem: <
    name: "e"
    key: <
      key: "key"
      value: "k1"
    >
  >
  elem: <
    name: "f"
  >
  elem: <
    name: "g"
  >
>

Multiple paths are supported. Multiple notification messages are triggered in response to each path. For example:

path <
  elem <
    name: "interface"
    key <
      key: "name"
      value: "mgmt0"
    >
  >
>
path <
  elem <
    name: "system"
  >
>
type: 1
encoding: JSON_IETF

Data node values

The value of a data node can be the following:

scalar types, such as a string in the string_val field, int64 in the int_val field, unit64 in the uint_val field, bool in the bool_val field, bytes, and float in the float_val field
additional types used in some schema languages, such as decimal64 in the decimal_val field and ScalarArray in the leaflist_val field
structured data types

Structured data types

When structured data is sent in an update message, it is serialized according to supported encoding, as shown in the following table.

Table 2. Encoding for structured data
Data type	Description	Field
ASCII	An ASCII encoded string	ascii_val
PROTO	A Protobuf encoded message using protobuf.any	any_val
JSON_IETF	A JSON encoded string using JSON encoding compatible with RFC 7951	json_ietf_val

Data model selection using gNMI origin

Within a gNMI request, the origin extension allows clients to specify which data model to interact with: OpenConfig (openconfig), native (native or srlinux_native), or CLI (cli or srlinux_cli).

Clients can specify a value for the origin in the path prefix or in one or more paths, but not both at once. When a request specifies the origin in the path prefix, SR Linux uses the specified data model to process all operations within the transaction.

Note: If a request includes a path prefix, the prefix must specify any required origin.

If no origin is specified in a request, SR Linux handles the request based on the data model specified under system gnmi-server network-instance yang-models (set to native by default).

SR Linux deviates from the gNMI specification in that it intrinsically links all origins such that a change in one data model produces the matching change in the other.

The following table describes the usage of the origin field in the message types where it is typically used.

Table 3. Purpose of origin field by message type
Message type	Purpose of `origin` field
SetRequest	Specifies the schema to use to modify the target configuration
GetRequest	Retrieves the contents of the specified schema
GetResponse	Indicates that the payload contains data from the specified <origin, path> schema
SubscribeRequest	Subscribes to paths within the specified schema
SubscribeResponse	Indicates the update corresponds to the specified <origin, path> tuple

Multiple path origins

If a SetRequest specifies more than one origin (for example, it contains two operations each with different path origins), the updates are processed as a single transaction. In this case, all operations must succeed for the SetResponse to return a success message. If any of the operations fail, the contents of all origins roll back, and the SetResponse returns an error.

You can specify mixed origins combining OpenConfig with native YANG or with CLI. In either case, SR Linux applies the OpenConfig origin first, followed by the native or CLI origin.

The following example shows the OpenConfig origin defined in the path prefix:

Origin defined in path prefix

prefix {
  origin: "openconfig"
}
path {
  elem {
    name: "interfaces"
  }
  elem {
    name: "interface"
    key {
      key: "name"
      value: "ethernet-1/1"
    }
  }
  elem {
    name: "state"
  }
  elem {
    name: "description"
  }
}
type: ALL
encoding: JSON_IETF

CLI configuration with gNMI origin

SR Linux supports setting the gNMI origin to CLI (cli or srlinux_cli), which allows gNMI clients to apply CLI configurations. In this case, SR Linux ignores any defined path and enters and commits the configuration included in the update or replace operation as CLI input.

The value defined in the CLI origin is encoded as ASCII and supports both the tree-based CLI commands as displayed using the SR Linux info command or the full-context set / commands as shown using the info flat command.

Delete operations are not supported with origin CLI.

If a SetRequest replace operation contains only the CLI origin, SR Linux treats the operation as a full device configuration replacement. The whole running configuration is replaced with the CLI commands applied over a blank configuration.

SR Linux supports only one CLI replace operation per SetRequest. However, one or more update operations can follow the replace operation, in which case the updates are appended to the contents of the replace operation.

The following example shows a SetRequest that uses CLI origin within the update operation:

SetRequest with CLI origin

update: <
  path: <
    origin: "cli"
  >
  val: <
    ascii_val: "/interface ethernet-1/1 admin-state disable"
  >
>

gNMI Get RPC

The Get RPC allows you to 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.

GetRequest message

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 the following table.

Table 4. GetRequest fields
Field	Definition
path	Path (or set of paths) for the requested data view. Wildcards are permitted.
type	Type of data requested. Supported options are: CONFIG (configurable read/write data) STATE (non-configurable read-only data)
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

GetResponse message

The GetResponse message uses the fields shown in the following table.

Table 5. GetResponse fields
Field	Definition
notification	Set of notification messages for each path specified in the GetRequest.
extension	Repeated field to carry gNMI extensions

gNMI Set RPC

The Set RPC allows you to 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.

SetRequest message

The SetRequest message uses the fields shown in the following table.

Table 6. SetRequest fields
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
union_replace	A set of update messages of mixed origin 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:

path - the path of the element to be modified
value - a value to apply to the specified node

All changes to the state included in a SetRequest message are considered 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.

SetResponse message

The SetResponse message uses the fields shown in the following table.

Table 7. SetResponse fields
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: timestamp - time when the SetRequest message was accepted path - path defined in SetRequest message. A prefix may be present to reduce repetition of path elements. op - the operation performed on the path (delete, replace, or update) message - a status message
extension	Repeated field to carry gNMI extensions

gNMI Subscribe RPC

SubscribeRequest message

The SubscribeRequest message uses the fields shown in the following table.

Table 8. SubscribeRequest fields
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.

SubscriptionList message

A SubscriptionList message indicates a set of paths where common subscription behavior is required. The SubscriptionList message uses the fields shown in the following table.

Table 9. SubscriptionList fields
Field	Definition
subscription	A set of subscription messages indicating the paths associated with the subscription
mode	Type of subscription to create: ONCE STREAM (default) ON_CHANGE SAMPLE sample_interval TARGET_DEFINED
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.

ON_CHANGE - Data updates are only sent when the value of the data item changes.
SAMPLE - Data is sent at specified intervals as specified in the sample_interval field. The maximum sample rate is a 64-bit integer in nanoseconds and minimum is 0.
TARGET_DEFINED - The target determines the best subscription type to create on a per-leaf basis. For example, if the path specified refers to leaves that are event-driven, then an ON_CHANGE subscription may be created. If the data represents counters values, a SAMPLE subscription may be created.

SubscribeResponse message

The SubscribeResponse message uses the fields shown in the following table.

Table 10. SubscribeResponse fields
Field	Definition
update OR sync_response	A response field. Only one type can be specified per message: update - message providing an update value for a subscribed data entity sync_response - a Boolean field indicating that all data values corresponding to the paths have been transmitted at least once (not used with ONCE mode subscriptions)
extension	Repeated field to carry gNMI extensions

gNMI Capabilities RPC

The Capabilities RPC allows you to 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 uses, and the encoding used for data.

CapabilityRequest message

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.

CapabilityRequest message

message CapabilityRequest {
 repeated gnmi_ext.Extension extension = 1;
}

CapabilityResponse message

A CapabilityResponse message is sent from the target and includes the following fields:

supported_models - a set of ModelData messages describing each model supported by the target
supported_encodings - an enumerated field describing the data encodings supported by the target (ASCII and JSON_IETF are supported)
gNMI_version - the version of the gNMI service supported by the target
encoding - a repeated field for gNMI extensions

CapabilityResponse message

message CapabilityResponse {
 repeated ModelData supported_models = 1;
 repeated Encoding supported_encodings = 2;
 string gNMIversion = 3;
 repeated gnmi_ext.Extension extension = 4;
}

Candidate mode

gNMI uses its own private exclusive candidate that restricts other users or services from making simultaneous changes to a configuration. If another exclusive session is already active, any attempted gNMI updates fail with an error.

The gNMI server uses the private exclusive candidate name gnmirpc-<n>, where <n> is a 32-bit number starting at 1 that increments for every request received, but resets on a gNMI server restart.

gNMI examples

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:

gnmi_get — used for simple GetRequests
gnmi_set — used for simple SetRequests
gnmi_cli — used for SubscribeRequests, and advanced GetRequests and SetRequests
gnmi_capabilities — used for CapabilityRequests

gnmi_get examples

The get gNMI-RPC allows you to retrieve state and configuration from a datastore. The following examples are shown:

get all request
get interface with wildcard key request

get all request

# gnmi_get -target_addr 172.18.0.6:50052 -insecure -xpath '/'
== getRequest:
path: <
>
encoding: JSON_IETF

Response (get all)

notification: <
  timestamp: 1565672122888042050
  update: <
    path: <
    >
    val: <
      json_ietf_val: "{\n \"srl_nokia-acl:acl\": {\n \"ipv4-
      filter\" ---- snip ---- ]\n }\n}\n"
    >
  >
>

get interface with wildcard key request

# gnmi_get -target_addr 172.18.0.6:50052 -insecure -xpath
'/interface[name=mgmt0]/subinterface[index=*]'
== getRequest:
path: <
  elem: <
    name: "interface"
    key: <
      key: "name"
      value: "mgmt0"
    >
  >
  elem: <
    name: "subinterface"
    key: <
      key: "index"
      value: "*"
    >
  >
>
encoding: JSON_IETF

Response (get interface with wildcard key)

notification: <
  timestamp: 1565671919030747121
  update: <
    path: <
      elem: <
        name: "srl_nokia-interfaces:interface"
        key: <
          key: "name"
          value: "mgmt0"
        >
      >
    >
    val: <
      json_ietf_val: "{\n \"name\": \"mgmt0\",\n \"subinterface\":
      [\n {\n \"index\": 0,\n \"admin-state\": \"enable\",\n
      \"ip-mtu\": 1500,\n \"ifindex\": 524288000,\n \"operstate\":
      \"up\",\n \"last-change\": \"2019-08-
      11T17:21:48.366Z\",\n \"ipv4\": {\n \"allow-directedbroadcast\":
      false,\n \"dhcp-client\": true,\n
      \"address\": [\n {\n \"ip-prefix\":in
      \"172.18.0.6/24\",\n \"origin\": \"dhcp\"\n }\n
      ],\n \"srl_nokia-interfaces-nbr:arp\": {\n
      \"timeout\": 14400,\n \"neighbor\": [\n {\n
      \"ipv4-address\": \"172.18.0.1\",\n \"link-layeraddress\":
      \"02:42:45:9D:DB:FC\",\n \"origin\":
      \"dynamic\",\n \"expiration-time\": \"2019-08-
      13T07:14:34.707Z\"\n },\n {\n
      \"ipv4-address\": \"172.18.0.2\",\n \"link-layeraddress\":
      \"02:42:AC:12:00:02\",\n \"origin\":
      \"dynamic\",\n \"expiration-time\": \"2019-08-
      13T05:17:51.893Z\"\n }\n ]\n }\n },\n
      \"ipv6\": {\n \"dhcp-client\": true,\n \"address\": [\n
      {\n \"ip-prefix\": \"2001:172:18::6/80\",\n
      \"origin\": \"dhcp\",\n \"status\": \"preferred\"\n
      },\n {\n \"ip-prefix\":
      \"fe80::42:acff:fe12:6/64\",\n \"origin\": \"linklayer\",\
      n \"status\": \"preferred\"\n }\n
      ],\n \"srl_nokia-interfaces-nbr:neighbor-discovery\": {\n
      \"dup-addr-detect\": true,\n \"reachable-time\": 30,\n
      \"stale-time\": 14400\n }\n },\n \"statistics\": {\n
      \"in-pkts\": \"5136\",\n \"in-octets\": \"438953\",\n
      \"in-error-pkts\": \"0\",\n \"in-discarded-pkts\": \"0\",\n
      \"in-terminated-pkts\": \"5136\",\n \"in-terminated-octets\":
      \"438953\",\n \"in-forwarded-pkts\": \"0\",\n \"inforwarded-
      octets\": \"0\",\n \"out-forwarded-pkts\":
      \"6062\",\n \"out-forwarded-octets\": \"2746613\",\n
      \"out-error-pkts\": \"0\",\n \"out-discarded-pkts\": \"0\",\n
      \"out-pkts\": \"6062\",\n \"out-octets\": \"2746520\"\n
      },\n \"srl_nokia-qos:qos\": {\n \"input\": {\n
      \"classifiers\": {\n \"ipv4-dscp\": \"default\",\n
      \"ipv6-dscp\": \"default\",\n \"mpls-tc\": \"default\"\n
      }\n }\n }\n }\n ]\n}\n"
    >
  >
>

gnmi_set examples

The set gNMI-RPC allows you to modify the state. The following examples are shown:

set delete request
set update all request

set delete request

# gnmi_set -target_addr 172.18.0.3:50052 -username admin -password
admin -insecure -delete /system/name/host-name
== setRequest:
delete: <
  elem: <
    name: "system"
  >
  elem: <
    name: "name"
  >
  elem: <
    name: "host-name"
  >
>

Response (set delete)

response: <
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "name"
    >
    elem: <
      name: "host-name"
    >
  >
  op: DELETE
>
timestamp: 1567203341816078044

set an update all request

# gnmi_set -target_addr 172.18.0.3:50052 -username admin -password
admin -insecure -update /system/name/host-name:replaced-host -replace
/system/name/domain-name:replaced-domain
== setRequest:
replace: <
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "name"
    >
    elem: <
      name: "domain-name"
    >
  >
  val: <
    string_val: "replaced-domain"
  >
>
update: <
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "name"
    >
    elem: <
      name: "host-name"
    >
  >
  val: <
    string_val: "replaced-host"
  >
>

Response (set update all)

response: <
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "name"
    >
    elem: <
      name: "domain-name"
    >
  >
  op: REPLACE
response: <
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "name"
    >
    elem: <
      name: "host-name"
    >
  >
  op: UPDATE
>
timestamp: 1567204165851469784

gnmi_cli examples

The cli gNMI-RPC allows you to subscribe and receive updates on the state of a data instance. The following examples are shown:

Subscribe - ONCE for all (one-time subscription) request
Subscribe - STREAM ON_CHANGE interface (long term subscription) request

In these examples, -qt specifies the subscription type. ONCE mode is the default and therefore is not shown in the first example.

Subscribe ONCE for all request

# gnmi_cli -a 172.18.0.6:50052 -insecure -q '/'

Response (subscribe ONCE for all)

{
  "acl": {
    "ipv4-filter": {
      "allow_sip_dip": {
        "entry": {
          "10": {
            "action": {
              "accept": {
                "log": "false"
              }
-- Snip –
}

Subscribe STREAM ON_CHANGE interface request

# gnmi_cli -a 172.18.0.6:50052 -insecure --qt streaming -q
'/interface[name=mgmt0]'

Response (Subscribe STREAM ON_CHANGE interface)

{
  "interface": {
    "mgmt0": {
      "admin-state": "enable",
      "ethernet": {
      "flow-control": {
        "receive": "false"
      },
      "hw-mac-address": "02:42:AC:12:00:06",
      "statistics": {
        "in-crc-errors": "0",
        "in-fragment-frames": "0",
        "in-jabber-frames": "0",
        "in-mac-pause-frames": "0",
        "in-oversize-frames": "0",
        "out-mac-pause-frames": "0"
      }
    },
    "ifindex": "524304383",
    "last-change": "2019-08-30T18:44:45.490Z",
    "mtu": "1514",
    "oper-state": "up",
    "statistics": {
      "carrier-transitions": "1",
      "in-broadcast-pkts": "5",
      "in-errors": "0",
      "in-fcs-errors": "0",
      "in-multicast-pkts": "1356",
      "in-octets": "612022",
      "in-unicast-pkts": "4662",
      "out-broadcast-pkts": "1",
      "out-errors": "0",
      "out-multicast-pkts": "456",
      "out-octets": "2724476",
      "out-unicast-pkts": "5505"
    },
    "subinterface": {
      "0": {
        "admin-state": "enable",
        "ifindex": "524288000",
        "ip-mtu": "1500",
        "ipv4": {
          "address": {
            "172.18.0.6/24": {
              "origin": "dhcp"
            }
          },
          "allow-directed-broadcast": "false",
          "arp": {
            "neighbor": {
              "172.18.0.1": {
                "expiration-time": "2019-08-31T01:13:22.987Z",
                "link-layer-address": "02:42:45:9D:DB:FC",
                "origin": "dynamic"
              },
              "172.18.0.2": {
                "expiration-time": "2019-08-30T22:44:54.422Z",
                "link-layer-address": "02:42:AC:12:00:02",
                "origin": "dynamic"
              }
            },
            "timeout": "14400"
          },
          "dhcp-client": "true"
        },
        "ipv6": {
          "address": {
            "2001:172:18::6/80": {
              "origin": "dhcp",
              "status": "preferred"
            },
           "fe80::42:acff:fe12:6/64": {
              "origin": "link-layer",
              "status": "preferred"
            }
          },
          "dhcp-client": "true",
          "neighbor-discovery": {
            "dup-addr-detect": "true",
            "reachable-time": "30",
            "stale-time": "14400"
          }
        },
        "last-change": "2019-08-30T18:44:45.490Z",
        "oper-state": "up",
        "qos": {
          "input": {
            "classifiers": {
              "ipv4-dscp": "default",
              "ipv6-dscp": "default",
              "mpls-tc": "default"
            }
          }
        },
        "statistics": {
          "in-discarded-pkts": "0",
          "in-error-pkts": "0",
          "in-forwarded-octets": "0",
          "in-forwarded-pkts": "0",
          "in-octets": "404380",
          "in-pkts": "4679",
          "in-terminated-octets": "404380",
          "in-terminated-pkts": "4679",
          "out-discarded-pkts": "0",
          "out-error-pkts": "0",
          "out-forwarded-octets": "2409995",
          "out-forwarded-pkts": "5511",
          "out-octets": "2409995",
          "out-pkts": "5511"
        }
      }
    },
    "vlan-tagging": "false"
  }
}
{
  "interface": {
    "mgmt0": {
      "statistics": {
        "in-octets": "615366"
      }
    }
  }
}
{
  "interface": {
    "mgmt0": {
      "statistics": {
        "in-unicast-pkts": "4693"
      }
    }
  }
}
{
  "interface": {
    "mgmt0": {
      "statistics": {
        "out-octets": "2736287"
      }
    }
  }
}
.
.
.

gnmi_capabilities example

The capabilities gNMI-RPC allows you to discover the capabilities of a specific gNMI server. The following example shows a request to obtain model, data encodings, and version for a specified server.

Request server capabilities for specified server

gnmi_capabilities   -username admin -password admin --target_addr [172.18.0.8]:50264

Response (request server capabilities)

supported_models: <
 name: "urn:srl_nokia/aaa:srl_nokia-aaa"
 organization: "Nokia"                                  
 version: "2020-12-31"
>                                                                                                                                   
supported_models: <                                          
 name: "urn:srl_nokia/aaa-types:srl_nokia-aaa-types"
 organization: "Nokia"                     
 version: "2019-11-30"
> 
.
.
.
supported_encodings: JSON_IETF
supported_encodings: ASCII
supported_encodings: PROTO
supported_encodings: 45
supported_encodings: 44
supported_encodings: 46
supported_encodings: 47
gNMI_version: "0.7.0"