cisco-ie / ios-xr-grpc-python

IOS-XR gRPC Python connectivity library.

gRPC for Cisco IOS-XR in Python

Author: Karthik Kumaravel

This package contains a library with the methods that are available to use over gRPC with IOS-XR boxes after 6.0.0. The API has several methods which allows a user to send simple RPC commands such as get and push using YANG and JSON.

The repo consists of two main components:

1. The compiled pb2 file from the proto definition.
2. A Python module accessing the pb2 file with the library bindings.

The repo also includes examples on how to use the library to interact with an IOS-XR device. If you want to create your own client, there is a walkthrough at the bottom of this page.

If you find any problems or need help, create an issue!

Installation

Either download this repository or install with pip install iosxr_grpc

It is always recommended to work in a virtual environment with something like virtualenv or pipenv.

gRPC Calls

Enable gRPC

SSH in to the router and turn on gRPC, below is an example configuration:

interface GigabitEthernet 0/0/0/0
 ipv4 address 192.168.1.2 255.255.255.0
 no shut

grpc
 port 57777
 !
!

Note: Default port is 57400, and IPv4 only.

Using TLS

1. Enable TLS in configuration, example:

grpc
  tls
  port 57777
  !
!

2. Copy the autogenerated .pem file to the 'keys' folder in the client directory.

scp [email protected]:/misc/config/grpc/ems.pem ./

Usage

from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient

from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
client = CiscoGRPCClient(
    <ip address>,
    <port>,
    <timeout>,
    <username>,
    <password>,
    <optional: tls key>,
    <optional: tls server name ('ems.cisco.com')>)
path = <yang path> # '{"openconfig-interfaces:interfaces": [null]}')
err, result = client.<operation>(path) # client.getconfig(path)

For a more in-depth look, check out the wiki!

Creating your own Client

To create a client of your own there are a few steps to follow.

• Download the proto file for IOS-XR's grpc: https://github.com/CiscoDevNet/grpc-getting-started
• Follow the instructions to generate the client/server code in python using the grpc-getting-started's proto file: http://www.grpc.io/docs/tutorials/basic/python.html#generating-client-and-server-code
• From here create a client, an example can be found here: http://www.grpc.io/docs/tutorials/basic/python.html#creating-the-client
• At this point you should have a client similar to the one in this repo

Useful Links

If you would like to test this all out with IOS-XRv, use the following link to request access to the vagrant box.

https://xrdocs.github.io/

Projects that use the python client

Solenoid - App that injects routes directly into Cisco's IOS-XR RIB table.

Pipedown - CDN router monitoring tool for data center connectivity.

ios-xr-grpc-python's Issues

Error in getting Interface Configs

When i try to get interface config with the following path it raises an error:

path_intf = '{"Cisco-IOS-XR-ifmgr-cfg:interface-configurations": [null]}'
getconfig(path_intf)

The following paths for example work ok:
path_isis = '{"Cisco-IOS-XR-clns-isis-cfg:isis": [null]}'
path_route_Static = '{"Cisco-IOS-XR-ip-static-cfg:router-static": [null]}'
path_telemetry = '{"Cisco-IOS-XR-telemetry-model-driven-cfg:telemetry-model-driven": [null]}'

For path_intf the following error is raised:

[libprotobuf ERROR C:\projects\protobuf\protobuf\src\google\protobuf\wire_format_lite.cc:626] String field 'IOSXRExtensibleManagabilityService.ConfigGetReply.yangjson' contains invalid UTF-8 data when parsing a protocol buffer. Use the 'bytes' type if you intend to send raw bytes.
Traceback (most recent call last):
File "C:\Users\jpgoncalves\AppData\Local\Programs\Python\Python36\lib\site-packages\grpc\beta_client_adaptations.py", line 131, in _next
return next(self._iterator)
File "C:\Users\jpgoncalves\AppData\Local\Programs\Python\Python36\lib\site-packages\grpc_channel.py", line 364, in next
return self._next()
File "C:\Users\jpgoncalves\AppData\Local\Programs\Python\Python36\lib\site-packages\grpc_channel.py", line 358, in _next
raise self
grpc._channel._Rendezvous: <_Rendezvous of RPC that terminated with:
status = StatusCode.INTERNAL
details = "Exception deserializing response!"
debug_error_string = "None"

Update required grpcio version

ios-xr-grpc-python/setup.py

Line 13 in 3e99c81

'grpcio==1.18.0',

The required version for grpcio is listed as 1.18.0, can this be updated to either be >= this version or the current version of grpcio 1.33.1? There appears to be an issue with the wheel of 1.18.0, leading to install issues when using pip.

Any way to load config changes without committing?

Hi,

I'm trying to use the cliconfig to load some configuration, e.g.,

>>> driver.cliconfig('ntp server 1.2.3.4')

>>> 

To my surprise, this operation did commit the changes on the device. I would have expected to have to explicitly invoke the CommitConfig directive (by issuing another RPC request) to commit.

That's probably the expected / designed behaviour. So my question is: how can you load some configuration (without committing directly), preview the diff, then issue a separate RPC in order to commit (i.e., commit only if the config diff looks good)?

Cheers,
-Mircea

Unable to connect to cisco xr device, throwing errors "AbortionError: AbortionError(code=StatusCode.UNAVAILABLE, details="failed to connect to all addresses")"

I am trying to connect to an xr device and unfortunately having issues.

options = 'ems.cisco.com'

client = CiscoGRPCClient('x.x.x.x', 57400, 10, 'username', 'password', pem, options)
client.getconfig('{"openconfig-interfaces:interfaces": [null]}')

This is throwing alerts as below, Any idea what might be the issue here. Appreciate your help.

/home/xxxx/ios-xr-grpc-python/iosxr_grpc/cisco_grpc_client.py in getconfig(self, path)
84 responses = self._stub.GetConfig(message, self._timeout, metadata=self._metadata)
85 objects, err = '', ''
---> 86 for response in responses:
87 objects += response.yangjson
88 err += response.errors

/home/xxx/gnmmi/lib/python3.6/site-packages/grpc/beta/_client_adaptations.py in next(self)
134
135 def next(self):
--> 136 return self._next()
137
138 def next(self):

/home/supanick/gnmmi/lib/python3.6/site-packages/grpc/beta/_client_adaptations.py in _next(self)
131 return next(self._iterator)
132 except grpc.RpcError as rpc_error_call:
--> 133 raise _abortion_error(rpc_error_call)
134
135 def next(self):

AbortionError: AbortionError(code=StatusCode.UNAVAILABLE, details="failed to connect to all addresses")

gRPC proto XML

Hi @skkumaravel,

Thanks a lot for providing these examples!

I've got just a quick question: is it possible to specify in the proto file to return XML instead of JSON?

Regards,
Mircea

Addressing mismatch

The addresses used in the example is different from the tutorials in xrdocs

Deadline Exceeded

hello, i tried to execute example on 6.1.1 IOS-XRv. output below:

vagrant@vagrant-ubuntu-trusty-64:~/cisco_grpc_python$ python grpc_example.py
Traceback (most recent call last):
File "grpc_example.py", line 15, in
main()
File "grpc_example.py", line 10, in main
result = client.getconfig(path)
File "/home/vagrant/cisco_grpc_python/client/cisco_grpc_client.py", line 58, in getconfig
for response in responses:
File "/usr/local/lib/python2.7/dist-packages/grpc/beta/_client_adaptations.py", line 153, in next
return self._next()
File "/usr/local/lib/python2.7/dist-packages/grpc/beta/_client_adaptations.py", line 147, in _next
raise _abortion_error(rpc_error_call)
grpc.framework.interfaces.face.face.ExpirationError: ExpirationError(code=StatusCode.DEADLINE_EXCEEDED, details="Deadline Exceeded")

How to use other .yang moduels?

Hi,
First of all, understand I am learning gRPC to use with our CiscoXR. Therefore if anything I ask seems amateurish, that is why.
I read though the wiki and Readme.
It looks like this repo has two .json files which you use as the structure for sending GRPC commands to adjust BGP.
How does one use other yang modules?
Looking at the yang/cisco repo, there are a variety of modules to use. Would like to use one based on my version (7.2.1).
I tried converting the same .yang module you used to xml then from xml to json, but the structure looks completely different.
How did you create / convert your .json files?

bump versions of grpcio and protobuf

suggestion, to upgrade requirements.txt packages of grpcio and protobuf

grpcio==1.36.1
protobuf==3.15.6

why?

add support for python 3.9+

tested locally

git clone https://github.com/cisco-ie/ios-xr-grpc-python.git
(modify requirements.txt)
pip3 install -e .

Defaulting to user installation because normal site-packages is not writeable
Obtaining file:///workspaces/cisco-devnet-quiz/classroom/solved/model-driven_programmability_stack/grpc/ios-xr-grpc-python
Collecting grpcio==1.36.1
  Using cached grpcio-1.36.1-cp39-cp39-manylinux2014_x86_64.whl (4.1 MB)
Requirement already satisfied: six>=1.5.2 in /home/vscode/.local/lib/python3.9/site-packages (from grpcio==1.36.1->iosxr-grpc==1.3) (1.15.0)
Collecting protobuf==3.15.6
  Using cached protobuf-3.15.6-cp39-cp39-manylinux1_x86_64.whl (1.0 MB)
Installing collected packages: protobuf, grpcio, iosxr-grpc
  Running setup.py develop for iosxr-grpc
Successfully installed grpcio-1.36.1 iosxr-grpc protobuf-3.15.6

setup.py also needs to be updated for pypi

from setuptools import setup


setup(name='iosxr_grpc',
      version='1.3',
      description='gRPC library for IOS-XR > 6.1.1',
      url='https://github.com/cisco-grpc-connection-libs/ios-xr-grpc-python',
      author='Karthik Kumaravel',
      authoer_email='[email protected]',
      licencse='Apache 2.0',
      packages=['iosxr_grpc'],
      install_requires=[
          'grpcio==1.36.1',
          'protobuf==3.15.6',
      ],
      zip_safe=False)

telemetry_collector.py

hi,

i'm trying to use your telemetry_collector.py and was wondering if you can help me understand how i would put the path inside the script to collect sensor data?

the current sensors that are enabled on my NCS are:

sensor-path Cisco-IOS-XR-shellutil-oper:system-time

sensor-path Cisco-IOS-XR-wdsysmon-fd-oper:system-monitoring/cpu-utilization

sensor-path Cisco-IOS-XR-nto-misc-oper:memory-summary/nodes/node/summary

sensor-path Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/latest/data-rate

sensor-path Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/latest/generic-counters

sensor-path Cisco-IOS-XR-ipv4-bgp-oper:bgp/instances/instance/instance-active/default-vrf/neighbors/neighbor