4. gNMI interface

The SR Linux provides a gNMI-based RPC for the modification and retrieval of a configuration. Supported RPCs are:

4.1. 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 Table 7.

Table 7: 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

4.1.1. Timestamps

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

4.1.2. 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:

notification: <

timestamp: (timestamp) // timestamp as int64

prefix: <

elem: <

elem: <

key: <

key: "name"

value: "b1"

elem: <

update: <

path: <

elem: <

value: <

val: <

json_val: "AStringValue"

update: <

path: <

elem: <

val: <

json_val: 10042 // converted to int representation

4.1.3. 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: <

elem: <

key: <

key: "key"

value: "k1"

elem: <

elem: <

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

path <

elem <

key <

key: "name"

value: "mgmt0"

path <

elem <

type: 1

encoding: JSON_IETF

4.1.4. 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

4.1.4.1. Structured data types

When structured data is sent in an update message, it is serialized according to supported encoding, as shown in Table 8.

Table 8: Encoding for structured data

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

4.2. gNMI get RPC

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.

4.2.1. GetRequest message

The GetRequest message uses the fields shown in Table 9.

Table 9: 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. If not specified, JSON is the default.
extension	Repeated field to carry gNMI extensions

4.2.2. GetResponse message

The GetResponse message uses the fields shown in Table 10.

Table 10: GetResponse fields

Field	Definition
notification	Set of notification messages for each path specified in the GetRequest; see Timestamps
extension	Repeated field to carry gNMI extensions

4.3. gNMI set RPC

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.

4.3.1. SetRequest message

The SetRequest message uses the fields shown in Table 11.

Table 11: 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
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 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.

4.3.2. SetResponse message

The SetResponse message uses the fields shown in Table 12.

Table 12: 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

4.4. gNMI subscribe RPC

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.

4.4.1. SubscribeRequest message

The SubscribeRequest message uses the fields shown in Table 13.

Table 13: 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.

4.4.1.1. SubscriptionList message

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

Table 14: 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)
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 ON_CHANGE mode is currently the only mode supported. When the ON_CHANGE mode is defined, data updates are only sent when the value of the data item changes.

4.4.2. SubscribeResponse message

The SubscribeResponse message uses the fields shown in Table 15.

Table 15: SubscribeResponse fields

Field

Definition

update

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

4.5. Candidate mode

The gNMI uses its own private candidate that allows multiple users or services to make simultaneous changes to a configuration.

4.6. gNMI examples

Open source clients can be used to run GetRequests, SetRequests, and subscriptions. 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

4.6.1. gnmi_get examples

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

Example 1: shows a get all request
Example 2: shows a get all response
Example 3: shows a get interface with wildcard key request
Example 4: shows a get interface with wildcard key response

Example 1: get all request

# gnmi_get -target_addr 172.18.0.6:50052 -insecure -xpath '/'

== getRequest:

path: <

encoding: JSON_IETF

Example 2: get all response

notification: <

timestamp: 1565672122888042050

update: <

path: <

val: <

json_ietf_val: "{\n \"srl_nokia-acl:acl\": {\n \"ipv4-

filter\" ---- snip ---- ]\n }\n}\n"

Example 3: 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: <

key: <

key: "name"

value: "mgmt0"

elem: <

key: <

key: "index"

value: "*"

encoding: JSON_IETF

Example 4: get interface with wildcard key response

notification: <

timestamp: 1565671919030747121

update: <

path: <

elem: <

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"

4.6.2. gnmi_set examples

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

Example 1: shows a set delete request
Example 2: shows a set delete response
Example 3: shows a set update all request
Example 4: shows a set update all response

Example 1: set a delete request

# gnmi_set -target_addr 172.18.0.3:50052 -username admin -password

admin -insecure -delete /system/name/host-name

== setRequest:

delete: <

elem: <

elem: <

elem: <

Example 2: set a delete response

response: <

path: <

elem: <

elem: <

elem: <

op: DELETE

timestamp: 1567203341816078044

Example 3: set a 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: <

elem: <

elem: <

val: <

string_val: "replaced-domain"

update: <

path: <

elem: <

elem: <

elem: <

val: <

string_val: "replaced-host"

Example 4: set a update all response

response: <

path: <

elem: <

elem: <

elem: <

op: REPLACE

response: <

path: <

elem: <

elem: <

elem: <

op: UPDATE

timestamp: 1567204165851469784

4.6.3. gnmi_cli example

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

Example 1: Subscribe - ONCE for all (one-time subscription) request
Example 2: Subscribe - ONCE for all (one-time subscription) response
Example 3: Subscribe - STREAM ON_CHANGE interface (long term subscription) request
Example 4: Subscribe - STREAM ON_CHANGE interface (long term subscription) response

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

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

Example 2: Subscribe ONCE for all response

{

"acl": {

"ipv4-filter": {

"allow_sip_dip": {

"entry": {

"10": {

"action": {

"accept": {

"log": "false"

}

-- Snip –

}

Example 3: Subscribe STREAM ON_CHANGE interface request

# gnmi_cli -a 172.18.0.6:50052 -insecure --qt streaming -q

'/interface[name=mgmt0]'

Example 4: Subscribe STREAM ON_CHANGE interface response

{

"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"

}