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 cisco@192.168.1.2:/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.