gNOI - Operation Interface

About gNOI

gRPC Network Operations Interface (gNOI) defines a set of gRPC-based micro-services for executing operational commands on network devices.

gNOI uses Google Remote Procedure Call (gRPC) as the transport protocol and the configuration is same as that of gNMI. For details on gNMI configuration, see gRPC Agent. To send gNOI RPC requests, user needs a client that implements the gNOI client interface for each RPC. In Cisco NX-OS Release 10.1(1) the gNOI defines Remote Procedure Calls (RPCs) for a limited number of components and some of them are related to hardware (like optical interfaces).

Proto files are defined for the gRPC micro-services and are available at GitHub.

Table 1. Supported gNOI RPCs
Proto gNOI RPC Supported
System Ping Yes
Traceroute Yes
Time Yes
SwitchControl Processor Yes
Reboot Yes
RebootStatus Yes
CancelReboot Yes
OS Activate Yes
Verify Yes
Cert LoadCertificate Yes
File Get Yes
Stat Yes
Remove Yes

Revision History

Release Description
10.1(1) gNOI RPCs are implemented with the equivalent CLI. The existing CLI restrictions or valid options remain as applicable
10.2(1) Add support for file.proto and cert.proto

Guidelines and Limitations for gNOI

The gNOI feature has the following guidelines and limitations:

  • A maximum of 16 active gNOI RPCs are supported.

  • The Cisco Nexus 9000 series switches would run one endpoint with one gNMI service and two gNOI microservices.

Configuring gNOI

gNMI is a child functionality of the gRPC agent. See gRPC Agent, to enable the gRPC agent. Currently there is no separate configuration for gNOI.

System .Proto

The System proto service is a collection of operational RPCs that allows the management of a target outside the configuration and telemetry pipeline.

The following are the RPC support details for System proto:

RPC Support Description Limitation
Ping ping/ping6 cli command Executes the ping command on the target and streams back the results. Some targets may not stream any results until all results are available. If a packet count is not explicitly provided, ping5 is used. do_not_resolve option is not supported.
Traceroute traceroute/traceroute6 cli command Executes the traceroute command on the target and streams back the results. Some targets may not stream any results until all results are available. Max hop count of 30 is used. itial_ttl, marx_ttl, wait, do_not_fragment, do_not_resolve and l4protocol options are not supported.
Time local time Returns the current time on the target. Typically used to test if the target is responding. -
SwitchControl Processor system switchover cli command Switches from the current route processor to the provided route processor. Switchover happens instantly and the response may not be guaranteed to return to the client. Switchover occurs instantly. As a result, the response may not be guaranteed to return to the client.
Reboot cli: reload [module] Causes the target to reboot. message option is not supported. Delay option is supported for switch reload, and the path option accepts one module number.
RebootStatus show version [module] cli command Returns the status of the reboot for the target. -
CancelReboot reload cancel Cancels any pending reboot request. -

Note

The SetPackage RPC is not supported.

OS .Proto

The OS service provides an interface for OS installation on a Target. The OS package file format is platform dependent. The platform must validate that the OS package that is supplied is valid and bootable. This must include a hash check against a known good hash. It is recommended that the hash is embedded in the OS package.

The Target manages its own persistent storage, and OS installation process. It stores a set of distinct OS packages, and always proactively frees up space for incoming new OS packages. It is guaranteed that the Target always has enough space for a valid incoming OS package. The currently running OS packages must never be removed. The Client must expect that the last successfully installed package is available.

The following are the RPC support details for OS proto:

RPC Support Description Limitation
Activate install all nxos bootflash:///img_name Sets the requested OS version as the version that is used at the next reboot. This RPC reboots the Target. Cannot rollback or recover if the reboot fails.
Verify show version Verify checks the running OS version. This RPC may be called multiple times while the Target boots until it is successful. -

Note

The Install RPC is not supported.

Cert .Proto

The certificate management service is exported by targets. Rotate, Install and other Certificate Proto RPCs are not supported.

RPC Support Description Limitation
LoadCertificate

crypto ca import <trustpoint>

pkcs12 <file> <passphrase>

 Loads a bundle of CA certificates. -

File .Proto

The file proto streams messages based on the features of the file.proto RPCs. Put and other RPCs that are not listed here are not supported in File Proto.

Get, Stat, and Remove RPCs support file systems such as - bootflash, bootflash://sup-remote, logflash, logflash://sup-remote, usb, volatile, volatile://sup-remote and debug.

The following are the RPC support details for File proto:

RPC Support Description Limitation
Get Get reads and streams the contents of a file from the target. The file is streamed by sequential messages, each containing up to 64 KB of data. A final message is sent prior to closing the stream that contains the hash of the data sent. An error is returned if the file does not exist or there was an error reading the file. Maximum file size limit is 32 MB.
Stat Stat returns metadata about a file on the target. An error is returned if the file does not exist or if there is an error in accessing the metadata. -
Remove Remove removes the specified file from the target. An error is returned if the file does not exist, if it is a directory, or the remove operation encounters an error. -

Factory Reset .Proto

This .proto currently defines only one RPC. Refer to https://github.com/openconfig/gnoi/blob/master/factory_reset/factory_reset.proto.

RPC Support Description Limitation
FactoryReset Executes the ping command on the target and streams back the results. Some targets may not stream any results until all results are available. If a packet count is not explicitly provided, ping5 is used. do_not_resolve option is not supported.

FactoryReset

The gNOI factory reset operation erases all persistent storage on the specified module. This includes configuration, all log data, and the full contents of flash and (Solid State Drives) SSDs. The reset boots to the last boot image, erases all storage including license. gNOI factory reset supports two modes:

  • A fast erase which can reformat and repartition only.

  • A secure erase which can erase securely and wipe the data which is impossible to recover.

Option Description Values
factory_os Specifies to rollback to the OS version as shipped from factory. Setting to true on NX-OS is not supported, and it is mandatory to preserve the current boot image.
zero_fill Specifies whether to perform more time consuming and comprehensive secure erase.

zero_fill = true: Specifies factory-reset module all preserve-image force.

zero_fill = false: Specifies factory-reset module all bypass-secure-erase preserve-image force.

Troubleshooting gNOI

Debug gNOI

To verify the gNOI status, enter the following commands.

Show Commands

Command Description
clear grpc gnoi rpc Serves to clean up the counters or calls.

debug grpc events {events|errors}

show grpc nxsdk event-history {events|errors}

Debugs the events and errors from the event history.
show grpc internal gnoi service statistics Display gNOI service statistics
show grpc internal gnoi rpc {summary|detail} An internal keyword command added for serviceability.
clear grpc gnoi rpc Serves to clean up the counters or calls.

Example Output

show grpc gnmi service statistics 
=============
gRPC Endpoint
=============

Vrf            : management
Server address : [::]:50051

Status         : Running - certificate expired
Cert notBefore : Jun 20 16:43:49 2023 GMT
Cert notAfter  : Jun 21 16:43:49 2023 GMT
Client Root Cert notBefore : n/a
Client Root Cert notAfter  : n/a

Max concurrent calls            :  16
Active calls                    :  0
show grpc internal gnoi rpc all summary
=============
gRPC Endpoint
=============
Vrf            : management
Server address : [::]:50051
RPC Type        State      Last Activity  Cnt Req    Cnt Resp   Client
--------------- ---------- -------------- ---------- ---------- ----------------------------------------
system.ping     End        01/12 20:22:06          1          6 ipv4:171.68.196.210:53222
system.time     Listen     01/12 20:21:57          0          0

Gathering Debug Logs

gNOI is a child service of the gRPC agent. For more information, see gRPC Agent chapter.