Arista Command eAPI (CAPI)
- The Arista Command API is a simple and complete API that allows you to configure and monitor your Arista switches.
- Once the API is enabled, the switch accepts commands using the industry standard CLI syntax, and responds with machine readable output and errors serialized in JSON, served over HTTP.
CONFIGURING CAPI:
- It is very easy to configure eAPI
- Although disabled by default, it is very simple to get the Command API server running on your switch.
- bash$ ssh username@myswitch
Password: <passw0rd>
myswitch> enable
myswitch# configure terminal
myswitch(config)# management api http-commands
myswitch(config-mgmt-api-http-cmds)# no shutdown
myswitch(config-mgmt-api-http-cmds)# show management api http-commands
Enabled: Yes
HTTPS server: running, set to use port 443
HTTP server: shutdown, set to use port 80
Local HTTP server: shutdown, no authentication, set to use port 8080
Unix Socket server: shutdown, no authentication
VRF: default
… - This enables eAPI only for HTTPS. For using HTTP, switch to it as shown below:
- From configure mode, enter management api http-commands mode. In this submode, you can turn on or off the server by typing [no] shutdown, switch between accepting HTTP or HTTPS traffic via [no] protocol http[s], and adjust the ports the server should listen on using protocol http[s] port <portNumber>.
- myswitch> enable
myswitch# configure terminal
myswitch(config)# management api http-commands
myswitch(config-mgmt-api-http-cmds)# [no] shutdown
myswitch(config-mgmt-api-http-cmds)# [no] protocol https [port <portNumber>]
myswitch(config-mgmt-api-http-cmds)# [no] protocol http [port <portNumber>]
myswitch(config-mgmt-api-http-cmds)# [no] protocol http localhost [port <portNumber>]
myswitch(config-mgmt-api-http-cmds)# [no] protocol unix-socket
- On-box usage of CAPI: It is often useful to run scripts that use Command API directly on the switch itself. The first is an HTTP server bound to localhost (on port 8080 by default), which only accepts connections arriving from the same machine. The other solution is a Unix domain socket. Both can be used simultaneously also.
- Once Command API is enabled then you access via the local domain socket unix:/var/run/command-api.sock
switch = Server( "unix:/var/run/command-api.sock" )
- If configured to use HTTP over localhost, your script can access the API as follows:
switch = Server( "http://localhost:8080/command-api" )
Configuring a Certificate:
- Because clients use HTTP basic authentication to send usernames and passwords to the switch, we recommend using HTTPS so no passwords are sent in the clear over the network.
- By default a self-signed certificate will be used.
- You can view the current certificate using show management api http-commands https certificate
Exploring the Command API:
- To explore the API, point your web browser to http[s]://<switch-name>/, after enabling Command API.
- This web-app lets you interactively explore the protocol, return values, and model documentation.
Using Command API with Python:
- Install jsonrpclib library for installing Python JSON-RPC:
admin:~ admin$ sudo pip install jsonrpclib
- from jsonrpclib import Server
- switch = Server( "https://username:passw0rd@myswitch/command-api" ) #Note that both username and password are compulsory. If no password, give the username itself in password field also
- response = switch.runCmds( 1, ["show version"] ) #instead of 1, we can also use “latest” to take latest version
- print "The switch's system MAC addess is", response[0]["systemMacAddress"]
- Another easy way is to import CAPIClient library and use as per its documentation on: https://github.com/arista-eosext/CAPIClient
How it Works:
- The client starts by sending a JSON-RPC request via an HTTP POST request to http://<yourswitch>/command-api, which encapsulates a list of CLI commands it wishes to run, and the switch replies with a JSON-RPC response containing the result of each CLI command that was executed.
- If any of the commands emit an error, no further commands from that request are executed, and the response from the switch will contain an error object containing the details of the error that occurred.
Command Specification:
- In most cases, the client will use a simple string to specify the CLI command in the cmds parameter in the request. In certain cases, however, clients may wish to specify additional parameters during the command's execution.
- To use complex commands, pass a JSON object in lieu of a string, with the following attributes:
- cmd (mandatory): specify the CLI command to run.
- input (optional): specify a string to be provided as standard input while running the cmd
- revision (optional): in the case of 'show' commands that have been modified over the course of different EOS releases, this parameter allows clients to request an old model format. At this time, all models are at revision 1, and this attribute will be ignored.
- For example, to set the message of the day to Hello World!, the client should set cmds to
[ "enable", "configure", { "cmd": "banner motd", "input": "Hello World!\nEOF" } ]
- Similarly, if the switch requires an enable password, the following cmds value would let you enter exec mode and clear interface counters
[ { "cmd": "enable", "input": "hunter2" }, "clear counters" ]
Error Codes:
- The responses generated by the client library usually follow language conventions.
- For example, in Python, an error response results in an Exception being thrown, while Javascript expects an error handler callback.
Unsupported Commands:
- Certain commands are not permitted and will always return an error.
- The largest class of such commands are interactive commands .ie. those that need a response back from user or shows output continuously to user:
- watch
- reload #can be overcome by using the non-interactive ‘reload now’ command
- The bash command is only allowed with the timeout <timeout> argument, ie. bash timeout <timeout> <ARG>.
- Commands that attempt to use CLI pipes are also not allowed.
- (e.g. show interfaces | grep Ethernet1 )
- Also, no abbreviations are allowed in commands. This is necessary because future versions of EOS may add more commands, rendering previous abbreviations ambiguous.
Unconverted Commands:
- Although you can access almost any CLI command via the Command API, not all show commands have been converted to return formatted data, and trying to run the command with the format parameter set to json will result in an error.
- However, you can still get the CLI ASCII output for the unconverted command by setting the format parameter to text.
SEE: Command documentation for the respective command: http://<Switch name>/documentation.html
