2.8. RPC API Configuration Guide

Overview

Function Introduction

RPC API service allows user to configure and monitor the switch system through Remote Procedure Calls (RPC) from your program.

The service currently supports JSON-RPC over HTTP protocol together with HTTP Basic authentication.

Principle Description

RPC API service uses standard JSON-RPC over HTTP protocol to communicate the switch and your program. User may issue switch CLI commands through JSON-RPC method: “executeCmds”. By default, the CLI mode is in privileged EXEC mode ().

User could send JSON-RPC request via an HTTP POST request to URL: http://:/command-api. The detailed JSON-RPC request and response are show below:

JSON-RPC Request

| {
| "params":[ Parameters for command
| {
| "format":"text", Expected response format, can be 'text' or 'json', the default format is 'text'
| "version":1, The API version
| "cmds":[ List of CLI commands
| "show run", CLI command 1
| "config t", CLI command 2
| "vlan database", CLI command 3
| "vlan 1-8", CLI command 4
| "interface eth-0-1", CLI command 5
| "switchport mode trunk", CLI command 6
| "switchport trunk allowed vlan add 2", CLI command 7
| "shutdown", CLI command 8
| "end", CLI command 9
| "show interface switchport" CLI command 10
| ]
| }
| ],
| "jsonrpc":"2.0", JSON RPC protocol version. Always 2.0.
| "method":"executeCmds", Method to run the switch CLI commands
| "id":"0f5177d3-da0c-4039-921d-87a4809c93e0" JSON RPC unique identifier
| }

JSON-RPC Response

| {
| "jsonrpc":"2.0", JSON RPC protocol version. Always 2.0.
| "id":"1dc4bfba-6a3b-49e6-8d5e-f70d4d8f7fbb", JSON RPC unique identifier
| "result":[ Result list of objects from each CLI command executed.
| {
| "sourceDetails":"version 7.0.6.fcsn!n ...", Output information of CLI Command 1.
| The Original ASCII output information returned from CLI command if this command is successfully executed.
| "errorCode":-1003, Error code if it is available.
| "errorDesc":"unsupported command...", Error description if it is available.
| "warnings":"% Invalid...", Warnings if it is available.
| Formatted JSON object will also be returned if it is available.
| },
| { }, Output information of CLI Command 2.
| { }, Output information of CLI Command 3.
| { }, Output information of CLI Command 4.
| { }, Output information of CLI Command 5.
| { }, Output information of CLI Command 6.
| { }, Output information of CLI Command 7.
| { }, Output information of CLI Command 8.
| { }, Output information of CLI Command 9.
| {
| "sourceDetails":" Interface name : eth-0-1\n Switchport mode : trunk\n ...\n"
| } Output information of CLI Command 10.
| ]
| }

Python Client Example Code

Here is an example code using “pyjsonrpc” library:

import pyjsonrpc
import json

http_client = pyjsonrpc.HttpClient(
  url = "<http://10.10.39.64:80/command-api>",
  username = "username",
  password = "password"
)

cmds = {}
cmd_list = ["show run", "config t", "vlan database", "vlan 1-8",
 "interface eth-0-1", "switchport mode trunk", "switchport
  trunk allowed vlan add 2", "shutdown", "end", "show interface
  switchport"]
cmds['cmds'] = cmd_list
cmds['format'] = 'text'
cmds['version'] = 1
try:
  response = http_client.call("executeCmds", cmds)
  print("json response:");
  json_result = json.dumps(response, indent=4)
  print(json_result)
except Exception, e:
  if e.code == 401:
    print "Unauthorized user"
  else:
    print e.message
    print e.data

Error code

Here is a list of JSON-RPC 2.0 error code:

| Error Code | Description |
| --- | --- |
| -32700 | Parse error |
| -32600 | Invalid Request |
| -32601 | Method not found |
| -32602 | Invalid param |
| -32603 | Internal error |

Here is a list of RPC-API error code:

| Error Code | Description |
| --- | --- |
| -1000 | General error |
| -2001 | JSON RPC API Error: unsupported API version |
| -2002 | JSON RPC API Error: must specify 'params' with 'cmds' in JSON
RPC |
| -2003 | JSON RPC API Error: unsupported command response format |
| -3001 | Command execution failed: timed out |
| -3002 | Command execution failed: unsupported command |
| -3003 | Command execution failed: unauthorized command |
| -3004 | Command execution failed: the string does not match any command in
current mode |
| -3005 | Command execution failed: can't convert to JSON format |
| -3006 | Command execution failed: command list too short |
| -3007 | Command execution failed: command list too long |

Configuration

Configuring RPC API service

User could enable the RPC API service by the following steps.

The default port is 80.

step 1 Enter the configure mode

Switch# configure terminal

step 2 Enable RPC API service

Switch(config)# service rpc-api enable

Use the following command to disable rpc-api service:

Switch(config)# service rpc-api disable

step 3 Exit the configure mode

Switch(config)# end

Configuring RPC API service with HTTP Authentication

User could configure the HTTP authentication mode of RPC API service.

Currently, only HTTP Basic authentication is supported. User will receive status code: 401 (Unauthorized access) if user provides in valid user name or password.

step 1 Enter the configure mode

Switch# configure terminal

Step 2 Set the username and password, then enable the rpc-api authentication

Switch(config)# username myuser password mypass privilege 4
Switch(config)# service rpc-api auth-mode basic

Use the following command to disable authentication:

Switch(config)# no service rpc-api auth-mode

HTTP authentication settings of RPC API service will take effect after you restart this service or reboot the system.

step 3 Exit the configure mode

Switch(config)# end

step 4 Validation

Switch# show services rpc-api
RPC API service configuration:
Server State : enable
Port : 80
Authentication Mode : basic
VRF : default

Application cases

N/A