eAPI and Unix Domain Socket

Introduction

Today’s data centers cry out for automation. There are many approaches that Network Operators can leverage, but one method that is very powerful is using Arista’s eAPI command interface. When eAPI is enabled, the switch accepts commands using Arista’s CLI syntax, and responds with machine-readable output and errors serialized in JSON, served over HTTP or HTTPS. It’s very easy to use and exceptionally powerful. Other blogs and articles have discussed the usage of eAPI for scripts. The purpose of this article is to cover a new access method introduced in EOS 4.14.5, which allows local access to the eAPI interface.

Since EOS 4.12, eAPI has been supported via HTTP/HTTPS. This provides a method of accessing switch information and actively configuring switches with both on switch scripts and off switch (e.g. centralized management server). In 4.14.5 we introduced the ability to leverage Unix Domain Sockets as another method of access to the Command API in EOS. Unix domain sockets are sometimes called “local” sockets. They reside only inside a single Unix filesystem and provide a secure mechanism for communicating locally with the OS, in this case the Arista switch. The Unix domain socket facility is a standard component of POSIX operating systems and is similar to the API of an internet socket but does not use an underlying network protocol for communication. The domain socket is instantiated as a file in the file system in which multiple processes can access at the same time. You are effectively using the Unix file permissions for access to the socket instead of the EOS authentication (such as local user accounts or AAA). This is of course for locally executed scripts only.

Enabling eAPI over Unix Sockets

The Unix Socket support is easy to enable in EOS. In your switch configuration, set the following parameters:

management api http-commands
   protocol unix-socket
   no shutdown

When it is enabled, both HTTPS and Unix Socket support is enabled. This allows you to continue to use remote scripts and local scripts. Once Command API is enabled then you can access the local domain socket unix:/var/run/command-api.sock

 

As an example, a simple script using eAPI over Unix Sockets can be built as follows:

#!/usr/bin/env python

from jsonrpclib import Server
switch = Server( "unix:/var/run/command-api.sock")
theversionoutput = switch.runCmds( 1,[ "show version"])
print "The switch's system MAC addess is", theversionoutput[0]["systemMacAddress"]

 

The EOS Command API is great for scripting and automation, including deploying switches or changing switch configuration. It’s also extremely powerful to use it for querying switch state. Leveraging eAPI as another tool in the automation toolbox can prove to be very useful in the modern datacenter. Now with Unix domain socket support, it adds additional versatility for locally executed extensions and scripts.

 

Note: For more information or to explore the API, enable the Command API in EOS and point your web browser to http[s]://<hostname>/. This webapp allows you to interactively explore the protocol, return values, and model documentation.