- Notifications
You must be signed in to change notification settings - Fork18
CLI and library wrapping gNMI functionality to ease usage with Cisco implementations in Python programs.
License
cisco-ie/cisco-gnmi-python
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This library wraps gNMI functionality to ease usage with Cisco implementations in Python programs. Derived fromopenconfig/gnmi.
This is not an officially supported Cisco product. This library is intended to serve as a gNMI client reference implementation and streamline development with Cisco products.
pip install cisco-gnmipython -c"import cisco_gnmi; print(cisco_gnmi)"cisco-gnmi --helpThis library covers the gNMI definedCapabilities,Get,Set, andSubscribe RPCs, and helper clients provide OS-specific recommendations. A CLI (cisco-gnmi) is also available upon installation. As commonalities and differences are identified between OS functionality this library will be refactored as necessary.
Several examples of library usage are available inexamples/. Thecisco-gnmi CLI script found atsrc/cisco_gnmi/cli.py may also be useful.
It ishighly recommended that users of the library learnGoogle Protocol Buffers syntax to significantly ease usage. Understanding how to read Protocol Buffers, and referencegnmi.proto, will be immensely useful for utilizing gNMI and any other gRPC interface.
Sincev1.0.5 a gNMI CLI is available ascisco-gnmi when this module is installed.Capabilities,Get, rudimentarySet, andSubscribe are supported. The CLI may be useful for simply interacting with a Cisco gNMI service, and also serves as a reference for how to use thiscisco_gnmi library. CLI usage is documented at the bottom of this README inCLI Usage.
Sincev1.0.0 a builder pattern is available withClientBuilder.ClientBuilder provides severalset_* methods which define the intendedClient connectivity and aconstruct method to construct and return the desiredClient. There are several major methods involved here:
set_target(...) Specifies the network element to build a client for. set_os(...) Specifies which OS wrapper to deliver. set_secure(...) Specifies that a secure gRPC channel should be used. set_secure_from_file(...) Loads certificates from file system for secure gRPC channel. set_secure_from_target(...) Attempts to utilize available certificate from target for secure gRPC channel. set_call_authentication(...) Specifies username/password to utilize for authentication. set_ssl_target_override(...) Sets the gRPC option to override the SSL target name. set_channel_option(...) Sets a gRPC channel option. Implies knowledge of channel options. construct() Constructs and returns the built Client.ClientBuilder can be chained for initialization or instantiated line-by-line.
fromcisco_gnmiimportClientBuilderbuilder=ClientBuilder('127.0.0.1:9339')builder.set_os('IOS XR')builder.set_secure_from_target()builder.set_call_authentication('admin','its_a_secret')client=builder.construct()# Or...client=ClientBuilder('127.0.0.1:9339').set_os('IOS XR').set_secure_from_target().set_call_authentication('admin','its_a_secret').construct()
Using an encrypted channel automatically getting the certificate from the device, quick for testing:
fromcisco_gnmiimportClientBuilderclient=ClientBuilder('127.0.0.1:9339').set_os('IOS XR').set_secure_from_target().set_call_authentication('admin','its_a_secret').construct()
Using an owned root certificate on the filesystem:
fromcisco_gnmiimportClientBuilderclient=ClientBuilder('127.0.0.1:9339').set_os('IOS XR').set_secure_from_file('ems.pem').set_call_authentication('admin','its_a_secret').construct()
Passing certificate content to method:
fromcisco_gnmiimportClientBuilder# Note reading as byteswithopen('ems.pem','rb')ascert_fd:root_cert=cert_fd.read()client=ClientBuilder('127.0.0.1:9339').set_os('IOS XR').set_secure(root_cert).set_call_authentication('admin','its_a_secret').construct()
Usage with root certificate, private key, and cert chain:
fromcisco_gnmiimportClientBuilderclient=ClientBuilder('127.0.0.1:9339').set_os('IOS XE').set_secure_from_file(root_certificates='rootCA.pem',private_key='client.key',certificate_chain='client.crt',).set_call_authentication('admin','its_a_secret').construct()
Client is a very barebones class simply implementingcapabilities,get,set, andsubscribe methods. It provides some context around the expectation for what should be supplied to these RPC functions and helpers for validation.
Methods are documented insrc/cisco_gnmi/client.py.
NXClient inherits fromClient and provides several wrapper methods which aid with NX-OS gNMI implementation usage. These aresubscribe_xpaths, and the removal ofget andset as they are not yet supported operations. These methods have some helpers and constraints around what is supported by the implementation.
Methods and usage examples are documented insrc/cisco_gnmi/nx.py.
XEClient inherits fromClient and provides several wrapper methods which aid with IOS XE gNMI implementation usage. These aredelete_xpaths,get_xpaths,set_json, andsubscribe_xpaths. These methods have some helpers and constraints around what is supported by the implementation.
Methods and usage examples are documented insrc/cisco_gnmi/xe.py.
XRClient inherits fromClient and provides several wrapper methods which aid with IOS XR gNMI implementation usage. These aredelete_xpaths,get_xpaths,set_json, andsubscribe_xpaths. These methods have some helpers and constraints around what is supported by the implementation.
Methods and usage examples are documented insrc/cisco_gnmi/xr.py.
gRPC Network Management Interface (gNMI) is a service defining an interface for a network management system (NMS) to interact with a network element. It may be thought of as akin to NETCONF or other control protocols which define operations and behaviors. The scope of gNMI is relatively simple - it seeks to "[define] a gRPC-based protocol for the modification and retrieval of configuration from a target device, as well as the control and generation of telemetry streams from a target device to a data collection system. The intention is that a single gRPC service definition can cover both configuration and telemetry - allowing a single implementation on the target, as well as a single NMS element to interact with the device via telemetry and configuration RPCs".
gNMI is a specification developed byOpenConfig, an operator-driven working-group. It is important to note that gNMI only defines a protocol of behavior - not data models. This is akin to SNMP/MIBs and NETCONF/YANG. SNMP and NETCONF are respectively decoupled from the data itself in MIBs and YANG modules. gNMI is a control protocol, not a standardization of data. OpenConfig does develop standard data models as well, and does have some specialized behavior with OpenConfig originating models, but the data models themselves are out of the scope of gNMI.
Requires Python and utilizespipenv for environment management. Manual usage ofpip/virtualenv is not covered. Usesblack for code formatting andpylint for code linting.black is not explicitly installed as it requires Python 3.6+.
git clone https://github.com/cisco-ie/cisco-gnmi-python.gitcd cisco-gnmi-python# If pipenv not installed, install!pip install --user pipenv# Now use Makefile...make setup# Or pipenv manually if make not presentpipenv --three install --dev# Enter virtual environmentpipenv shell# Work workexit
We useblack for code formatting andpylint for code linting.hygiene.sh will runblack against all of the code undergnmi/ except forprotoc compiled protobufs, and runpylint against Python files directly undergnmi/. They don't totally agree, so we're not looking for perfection here.black is not automatically installed due to requiring Python 3.6+.hygiene.sh will check for regular path availability and viapipenv, and otherwise falls directly topylint. Ifblack usage is desired, please install it intopipenv if using Python 3.6+ or separate methods e.g.brew install black.
# If using Python 3.6+pipenv install --dev black# Otherwise..../hygiene.sh
If a newgnmi.proto definition is released, useupdate_protos.sh to recompile. If breaking changes are introduced the wrapper library must be updated.
./update_protos.sh
The below details the currentcisco-gnmi usage options. Please note thatSet operations may be destructive to operations and should be tested in lab conditions.
cisco-gnmi --helpusage:cisco-gnmi <rpc> [<args>]Supported RPCs:capabilitiessubscribegetsetcisco-gnmi capabilities 127.0.0.1:57500cisco-gnmi get 127.0.0.1:57500cisco-gnmi set 127.0.0.1:57500 -delete_xpath Cisco-IOS-XR-shellutil-cfg:host-names/host-namecisco-gnmi subscribe 127.0.0.1:57500 -debug -auto_ssl_target_override -dump_file intfcounters.proto.txtSee <rpc> --help for RPC options.gNMI CLI demonstrating library usage.positional arguments: rpc gNMI RPC to perform against network element.optional arguments: -h, --help show this help message and exitThis command will output theCapabilitiesResponse tostdout.
cisco-gnmi capabilities 127.0.0.1:57500 -auto_ssl_target_overridecisco-gnmi capabilities --helpusage: cisco-gnmi [-h] [-os {None,IOS XR,NX-OS,IOS XE}] [-root_certificates ROOT_CERTIFICATES] [-private_key PRIVATE_KEY] [-certificate_chain CERTIFICATE_CHAIN] [-ssl_target_override SSL_TARGET_OVERRIDE] [-auto_ssl_target_override] [-debug] netlocPerforms Capabilities RPC against network element.positional arguments: netloc <host>:<port>optional arguments: -h, --help show this help message and exit -os {None,IOS XR,NX-OS,IOS XE} OS wrapper to utilize. Defaults to IOS XR. -root_certificates ROOT_CERTIFICATES Root certificates for secure connection. -private_key PRIVATE_KEY Private key for secure connection. -certificate_chain CERTIFICATE_CHAIN Certificate chain for secure connection. -ssl_target_override SSL_TARGET_OVERRIDE gRPC SSL target override option. -auto_ssl_target_override Use root_certificates first CN as grpc.ssl_target_name_override. -debug Print debug messages.[cisco-gnmi-python] cisco-gnmi capabilities redacted:57500 -auto_ssl_target_overrideUsername: adminPassword:WARNING:root:Overriding SSL option from certificate could increase MITM susceptibility!INFO:root:supported_models { name: "Cisco-IOS-XR-qos-ma-oper" organization: "Cisco Systems, Inc." version: "2019-04-05"}...This command will output theGetResponse tostdout.-xpath may be specified multiple times to specify multiplePaths for theGetRequest.
cisco-gnmi get 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_overridecisco-gnmi get --helpusage: cisco-gnmi [-h] [-xpath XPATH] [-encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF}] [-data_type {ALL,CONFIG,STATE,OPERATIONAL}] [-dump_json] [-os {None,IOS XR,NX-OS,IOS XE}] [-root_certificates ROOT_CERTIFICATES] [-private_key PRIVATE_KEY] [-certificate_chain CERTIFICATE_CHAIN] [-ssl_target_override SSL_TARGET_OVERRIDE] [-auto_ssl_target_override] [-debug] netlocPerforms Get RPC against network element.positional arguments: netloc <host>:<port>optional arguments: -h, --help show this help message and exit -xpath XPATH XPaths to Get. -encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF} gNMI Encoding. -data_type {ALL,CONFIG,STATE,OPERATIONAL} gNMI GetRequest DataType -dump_json Dump as JSON instead of textual protos. -os {None,IOS XR,NX-OS,IOS XE} OS wrapper to utilize. Defaults to IOS XR. -root_certificates ROOT_CERTIFICATES Root certificates for secure connection. -private_key PRIVATE_KEY Private key for secure connection. -certificate_chain CERTIFICATE_CHAIN Certificate chain for secure connection. -ssl_target_override SSL_TARGET_OVERRIDE gRPC SSL target override option. -auto_ssl_target_override Use root_certificates first CN as grpc.ssl_target_name_override. -debug Print debug messages.[cisco-gnmi-python] cisco-gnmi get redacted:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_overrideUsername: adminPassword:WARNING:root:Overriding SSL option from certificate could increase MITM susceptibility!INFO:root:notification { timestamp: 1585607100869287743 update { path { elem { name: "interfaces" } elem { name: "interface" } elem { name: "state" } elem { name: "counters" } } val { json_ietf_val: "{\"in-unicast-pkts\":\"0\",\"in-octets\":\"0\"...Please note thatSet operations may be destructive to operations and should be tested in lab conditions. Behavior is not fully validated.
cisco-gnmi set --helpusage: cisco-gnmi [-h] [-update_json_config UPDATE_JSON_CONFIG] [-replace_json_config REPLACE_JSON_CONFIG] [-delete_xpath DELETE_XPATH] [-no_ietf] [-dump_json] [-os {None,IOS XR,NX-OS,IOS XE}] [-root_certificates ROOT_CERTIFICATES] [-private_key PRIVATE_KEY] [-certificate_chain CERTIFICATE_CHAIN] [-ssl_target_override SSL_TARGET_OVERRIDE] [-auto_ssl_target_override] [-debug] netlocPerforms Set RPC against network element.positional arguments: netloc <host>:<port>optional arguments: -h, --help show this help message and exit -update_json_config UPDATE_JSON_CONFIG JSON-modeled config to apply as an update. -replace_json_config REPLACE_JSON_CONFIG JSON-modeled config to apply as a replace. -delete_xpath DELETE_XPATH XPaths to delete. -no_ietf JSON is not IETF conformant. -dump_json Dump as JSON instead of textual protos. -os {None,IOS XR,NX-OS,IOS XE} OS wrapper to utilize. Defaults to IOS XR. -root_certificates ROOT_CERTIFICATES Root certificates for secure connection. -private_key PRIVATE_KEY Private key for secure connection. -certificate_chain CERTIFICATE_CHAIN Certificate chain for secure connection. -ssl_target_override SSL_TARGET_OVERRIDE gRPC SSL target override option. -auto_ssl_target_override Use root_certificates first CN as grpc.ssl_target_name_override. -debug Print debug messages.Let's create a harmless loopback interface based fromopenconfig-interfaces.yang.
config.json
{"openconfig-interfaces:interfaces": {"interface": [ {"name":"Loopback9339" } ] }}[cisco-gnmi-python] cisco-gnmi set redacted:57500 -os "IOS XR" -auto_ssl_target_override -update_json_config config.jsonUsername: adminPassword:WARNING:root:Overriding SSL option from certificate could increase MITM susceptibility!INFO:root:response { path { origin: "openconfig-interfaces" elem { name: "interfaces" } } message { } op: UPDATE}message {}timestamp: 1585715036783451369And on IOS XR...a loopback interface!
...interface Loopback9339!...This command will output theSubscribeResponse tostdout or-dump_file.-xpath may be specified multiple times to specify multiplePaths for theGetRequest.
cisco-gnmi subscribe 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_overridecisco-gnmi subscribe --helpusage: cisco-gnmi [-h] [-xpath XPATH] [-interval INTERVAL] [-mode {TARGET_DEFINED,ON_CHANGE,SAMPLE}] [-suppress_redundant] [-heartbeat_interval HEARTBEAT_INTERVAL] [-dump_file DUMP_FILE] [-dump_json] [-sync_stop] [-sync_start] [-encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF}] [-os {None,IOS XR,NX-OS,IOS XE}] [-root_certificates ROOT_CERTIFICATES] [-private_key PRIVATE_KEY] [-certificate_chain CERTIFICATE_CHAIN] [-ssl_target_override SSL_TARGET_OVERRIDE] [-auto_ssl_target_override] [-debug] netlocPerforms Subscribe RPC against network element.positional arguments: netloc <host>:<port>optional arguments: -h, --help show this help message and exit -xpath XPATH XPath to subscribe to. -interval INTERVAL Sample interval in seconds for Subscription. Defaults to 10. -mode {TARGET_DEFINED,ON_CHANGE,SAMPLE} SubscriptionMode for Subscription. Defaults to SAMPLE. -suppress_redundant Suppress redundant information in Subscription. -heartbeat_interval HEARTBEAT_INTERVAL Heartbeat interval in seconds. -dump_file DUMP_FILE Filename to dump to. Defaults to stdout. -dump_json Dump as JSON instead of textual protos. -sync_stop Stop on sync_response. -sync_start Start processing messages after sync_response. -encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF} gNMI Encoding. Defaults to whatever Client wrapper prefers. -os {None,IOS XR,NX-OS,IOS XE} OS wrapper to utilize. Defaults to IOS XR. -root_certificates ROOT_CERTIFICATES Root certificates for secure connection. -private_key PRIVATE_KEY Private key for secure connection. -certificate_chain CERTIFICATE_CHAIN Certificate chain for secure connection. -ssl_target_override SSL_TARGET_OVERRIDE gRPC SSL target override option. -auto_ssl_target_override Use root_certificates first CN as grpc.ssl_target_name_override. -debug Print debug messages.[cisco-gnmi-python] cisco-gnmi subscribe redacted:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_overrideUsername: adminPassword:WARNING:root:Overriding SSL option from certificate could increase MITM susceptibility!INFO:root:Dumping responses to stdout as textual proto ...INFO:root:Subscribing to:/interfaces/interface/state/countersINFO:root:update { timestamp: 1585607768601000000 prefix { origin: "openconfig" elem { name: "interfaces" } elem { name: "interface" key { key: "name" value: "Null0" } } elem { name: "state" } elem { name: "counters" } } update { path { elem { name: "in-octets" } } val { uint_val: 0 } }...cisco-gnmi-python is licensed asApache License, Version 2.0.
Open an issue :)
About
CLI and library wrapping gNMI functionality to ease usage with Cisco implementations in Python programs.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors7
Uh oh!
There was an error while loading.Please reload this page.