Capabilities

The capabilities of RPC returns to the list of capabilities of the gNMI service. The response message to an RPC request includes the gNMI service version, version data models, and data encode supported by the server.

Guidelines and Limitations for Capabilities

The following are the guidelines and limitations for capabilities:

Example Client Output

Below mentioned the example of client output for Capabilities. Considering the feature openconfig is enabled.

This examples shows the support to YANG model, gNMI version, and the supported encodes.

$ ./gnmi_cli -a 172.1.1.1:50051 -ca_crt ./grpc.pem -insecure -capabilities
supported_models: <
  name: "Cisco-NX-OS-device"
  organization: "Cisco Systems, Inc."
  version: "2019-11-13"
> 
supported_models: <
  name: "openconfig-acl"
  organization: "OpenConfig working group"
  version: "1.0.0"
> 
supported_models: <
  name: "openconfig-bgp-policy"
  organization: "OpenConfig working group"
  version: "4.0.1"
> 
.
.
.
supported_models: <
  name: "openconfig-spanning-tree"
  organization: "OpenConfig working group"
  version: "0.2.0"
> 
supported_models: <
  name: "openconfig-system"
  organization: "OpenConfig working group"
  version: "0.3.0"
> 
supported_models: <
  name: "openconfig-telemetry"
  organization: "OpenConfig working group"
  version: "0.5.1"
> 
supported_models: <
name: "openconfig-vlan"
  organization: "OpenConfig working group"
  version: "3.0.2"
> 
supported_models: <
  name: "DME"
  organization: "Cisco Systems, Inc."
> 
supported_models: <
  name: "Cisco-NX-OS-Syslog-oper"
  organization: "Cisco Systems, Inc."
  version: "2019-08-15"
> 
supported_encodings: JSON
supported_encodings: PROTO
gNMI_version: "0.5.0"

Guidelines and Limitations for Get

The following are guidelines and limitations for Get:

• GetRequest encode supports only the JSON format.

• For the GetRequest.type, only DataType CONFIG and STATE have correlation and the expression in YANG format. The operation is not supported.

• You cannot have both OpenConfig (OC) YANG and device YANG paths in a single request. A single request has only one path.

• GetRequest for root path ("/": everything from all models) is not permitted.

• gNMI Get returns all default value. See Report-all mode RFC 6243 [4].

• Get does not support the Cisco-NX-OS-syslog-oper model.

• To retrieve openconfig-procmon data, you can send a query to the path /system/processes or /system.

  Note	Before Cisco NX-OS Release 10.3(x), you cannot retrieve data from the /system path.

• The following optionals are not supported:

  • Path prefix

  • Path alias

  • Wildcards in the path

• You can request 10 paths in a single GetReqeuest.

• If the return value of size in GetResponse is more than 12 MB, the system displays the error status grpc::RESOURCE_EXHAUSTED.

• The maximum receive buffer size of gRPC is 8 MB.

• If you perform an Get operation for a switch which has more configuration, the gRPC process consumes all available memory. If the memory exhausts, the below syslog is generated:

  MTX-API: The memory usage is
          reaching the max memory resource limit (3072) MB

  If the memory exhausts consecutively, the below syslog is generated:

  The process has become unstable and
          the feature should be restarted.

  Cisco recommends you to restart the gRPC feature for normal functioning of gNMI transactions.

• The maximum number of total concurrent sessions for Get is 75% of maximum configured concurrent calls. For an example, if the MTX concurrent calls are configured to 16, the maximum number of total concurrent sessions for Get is 12.

• The total number of concurrent sessions for Get and Set is configured max gNMI concurrent-1.

  For an example, if gNMI concurrent calls are configured to 16, the maximum number of total concurrent sessions for Get and Set is 15.

Guidelines and Limitations for Set

The following are guidelines and limitations for Set:

• SetRequest encode supports only JSON format.

• You cannot have both OpenConfig (OC) YANG and device YANG paths in a single request. A single request has only one path.

• The following optionals are not supported:

  • Path prefix

  • Path alias

  • Wildcards in the path

• You can request 20 paths in a single SetReqeuest.

• The maximum receive buffer size of gRPC is 8 MB.

• The maximum number of total concurrent sessions for Get and Set is configured maximum gNMI concurrent calls. For an example, if the gNMI concurrent calls are configured to 16, the maximum number of total concurrent sessions for Get and Set is 15.

• If you perform a Set::Delete RPC operation for a switch, if a configuration is bulky, an MTX warning message is generated as shown below:

  Configuration size for this
          namespace exceeds operational limit. Feature may become unstable and require
          restart.

Guidelines and Limitations

The following are guidelines and limitations for Set subscription:

• The following flags are not supported:

  • Aliases

  • allow_aggregation

  • extensions

  • prefix

  • QoS

• Make sure that all paths within the same subscription request must have the same sample interval. If the same path requires different sample intervals, you must create multiple subscriptions.

gNMI Subscribe Options

The following table lists the subscribe option modes:

To Set Modes

Each mode requires 2 settings, such as inside subscription and outside subscription. The following mentioned the combination of subscriptions:

• ONCE: SAMPLE, ONCE

• POLL: SAMPLE, POLL

• STREAM: SAMPLE, STREAM

• ON_CHANGE: ON_CHANGE, STREAM

• TARGET_DEFINED: TARGET_DEFINED, STREAM

Origin

• DME: Subscribing to DME model

• DEVICE: Subscribing to YANG model

• OPENCONFIG: Subscribing to OpenConfig model

Name

• DME: Subscribing to DME model

• Cisco-NX-OS-device: Subscribing to YANG model

Encoding

• JSON: Stream is sent in JSON format.

• PROTO: Stream is sent in original proto format.

Configuring Example of Payload

The following section lists client examples for a payload:

Subscribe to DME Stream/Sample

Guidelines and Limitations

The following are guidelines and limitations for Syslog Stream:

• An invalid syslog is not supported, such as a syslog with a filter or query condition is not supported.

• Syslog stream supports only below paths:

  • Cisco-NX-OS-Syslog-oper: syslog

  • Cisco-NX-OS-Syslog-oper: syslog messages

• Only stream sample and POLL modes are supported.

• Encoding formats that are supported are JSON and PROTO.

Original YANG Syslog Model

The following example shows the configuration of the YANG Syslog Model:

Note	By default, the time-zone field is empty. The time zone field is set when you configure clock format show-timezone syslog.

PYANG Tree for Syslog Native Yang Model:
>>> pyang -f tree Cisco-NX-OS-infra-syslog-oper.yang module: Cisco-NX-OS-syslog-oper
+--ro syslog
+--ro messages
+--ro message* [message-id]
+--ro message-id int32
+--ro node-name? string
+--ro time-stamp? uint64
+--ro time-of-day? string
+--ro time-zone? string
+--ro category? string
+--ro group? string
+--ro message-name? string
+--ro severity? System-message-severity
+--ro text? string

Subscribe Request

The following is an example for the subscribe request:

{
    "SubscribeRequest":
    [
        {
            "subscribe":
            {
                "subscription":
                [
                    {
                        "path":
                        {
                            "origin": "syslog-oper",
                            "elem":
                              [
                                {
                                    "name": "syslog"
                                },
                                {
                                    "name":"messages"
                                }
                            ]
                        },
                        "mode": "ON_CHANGE"
                    }
                ],
                "mode": "ON_CHANGE",
                "allow_aggregation" : false,
                "use_models":
                [
                    {
                        "name": "Cisco-NX-OS-Syslog-oper",
                        "organization": "Cisco Systems, Inc.",
                        "version": "0.0.0"
                    }
                ],
                "encoding":"JSON"
            }
        }
    ]
}

Example Response

The following is an output response example for PROTO encode:

[Subscribe]-------------------------------
Sat Aug 24 14:38:06 2019
### Generating request : 1 -----------
### Comment : STREAM request
### Delay : 2 sec(s) ...
### Delay : 2 sec(s) DONE

subscribe {
subscription {
path {
origin: "syslog-oper"
elem {
name: "syslog"
}
elem {
name: "messages"
}
}
mode: ON_CHANGE
}

use_models {
name: "Cisco-NX-OS-Syslog-oper"
organization: "Cisco Systems, Inc."
version: "0.0.0"
}
encoding: PROTO
}

Thu Nov 21 14:26:41 2019
Received response 3 --------------------------
update {
timestamp: 1574375201665688000
prefix {
origin: "Syslog-oper"
elem {
name: "syslog"
}
elem {
name: "messages"
}
}
…
update {
path {
elem {
name: "time-stamp"
}
}
val {
uint_val: 1574375200000
}
}
update {
path {
elem {
name: "severity"
}
}
val {
uint_val: 5
}
}
}

/Received -------------------------------------

The following is an example of output response for JSON encode:

[Subscribe]-------------------------------
### Reading from file ' testing_bl/stream_on_change/OC_SYSLOG.json '

Tue Nov 26 11:47:00 2019
### Generating request : 1 -----------
### Comment : STREAM request
### Delay : 2 sec(s) ...
### Delay : 2 sec(s) DONE
subscribe {
subscription {
path {
origin: "syslog-oper"
elem {
name: "syslog"
}
elem {
name: "messages"
}
}
mode: ON_CHANGE
}
use_models {
name: "Cisco-NX-OS-Syslog-oper"
organization: "Cisco Systems, Inc."
version: "0.0.0"
}
}

Tue Nov 26 11:47:15 2019
Received response 5 --------------------------
update {
timestamp: 1574797636002053000
prefix {
}
update {
path {
origin: "Syslog-oper"
elem {
name: "syslog"
}
}
val {
json_val: "[ { \"messages\" : [[ {\"message-id\":657},{\"node-name\":\"task-n9k-1\",\"time-stamp\":\"1574797635000\",\"time-of-day\":\"Nov 26 2019 11:47:15\",\"severity\":3,\"message-name\":\"HDR_L2LEN_ERR\",\"category\":\"ARP\",\"group\":\"ARP\",\"text\":\"arp [30318] Received packet with incorrect layer 2 address length (8 bytes), Normal pkt with S/D MAC: 003a.7d21.d55e ffff.ffff.ffff eff_ifc mgmt0(9), log_ifc mgmt0(9), phy_ifc mgmt0(9)\",\"time-zone\":\"\"} ]] } ]"
}
}
}