API

Overview

Background: JSON-RPC Format
Current API Calls (Methods)
OVX API Method Parameters
Notations
API Syntax

Synopsis

OpenVirteX defines two types of API, the Monitoring API and the Tenant API. The former is read-only and used to get configuration and state information, and the latter is used to create and configure virtual networks.

This page is divided into several sections. We first give a very brief overview of JSON-RPC syntax. We then give a brief overview of each OVX API call, the parameters available to the API, and the conventions used to describe the syntax of the API Calls.


Background: JSON-RPC Format

OVX follows the JSON-RPC 2.0 protocol. The syntax for the most commonly-used request and reply messages for the OVX API take the form:

request {"jsonrpc": "2.0", "method": "getSubnet", "params": {"tenant": 1}, "id": 0}
reply   {"jsonrpc": "2.0", "result": "192.168.1.0/16", "id": 0}

A request may also have no params:

{"jsonrpc": "2.0", "method": "getPhysicalTopology", "params":{}, "id":"ovxctl"}

And a reply may have a null result:

{"jsonrpc": "2.0", "result": null, "id": 0}

For the full details of JSON-RPC, refer to their specs.


Current API Calls (Methods)

The currently-available API functions are shown in the following two tables. We detail the parameters and results associated with these methods in the next few sections.

Monitoring API Calls
Method Name Method Description
getPhysicalTopology Get the current PhysicalNetwork topology
listVirtualNetworks List all of the virtual networks
getVirtualTopology Get the topology of a virtual network
getVirtualSwitchMapping Get the PhysicalSwitch(es) mapped to an OVXSwitch
getVirtualLinkMapping Get the PhysicalLink(s) mapped to a virtual link
getVirtualHosts Get all of the hosts on a virtual network. Hosts are described by virtual network addresses.
getPhysicalSwitchPorts Get all of the ports on a PhysicalSwitch
getPhysicalHosts Get all hosts from all virtual networks. Hosts are described by physical network addresses.
getSubnet Get the Address/Mask of a virtual network
getVirtualFlowtable Get the flow table of a OVXSwitch
getPhysicalFlowtable Get the flow table of a PhysicalSwitch
getVirtualAddressMapping Get the mappings between all available physical and virtual network addresses
getVirtualSwitchPorts Get all of the ports on a OVXSwitch
Tenant API Calls
Name Description
addControllers Add a new controller to connect a virtual switch (OVXSwitch) to
removeControllers Remove a controller from the list of controllers a OVXSwitch can connect to
createNetwork Create a new virtual network (OVXNetwork)
createSwitch Create a new OVXSwitch
createPort Add a new port to an OVXSwitch
SetOVXBigSwitchRouting Configure the routing method within a Big Virtual Switch (OVXBigSwitch)
connectHost Connect a host to an OVXNetwork
connectLink Add a virtual link to an OVXNetwork
setLinkPath Add a physical network path to a virtual link (OVXLink)
connectRoute Create a new route within a OVXBigSwitch
removeNetwork Remove an OVXNetwork
removeSwitch Remove an OVXSwitch from an OVXNetwork
removePort Remove a port from an OVXSwitch
disconnectHost Detach (remove) a host from a OVXNetwork
disconnectLink Detach (remove) a virtual link from an OVXNetwork
disconnectRoute Detach (remove) a route from an OVXBigSwitch
startNetwork Initialize (boot) an OVXNetwork
startSwitch Intialize (boot) an OVXSwitch
startPort Enable a port on an OVXSwitch
stopNetwork Disable an OVXNetwork temporarily
stopSwitch Disable an OVXSwitch temporarily
stopPort Disable a port on an OVXSwitch temporarily


OVX API Method Parameters

The following table lists the various parameters (values to the JSON “param” key) used by the OVX API. As a convention, we use the Keywords defined by OVX’s API handlers for each parameter as aliases:

Keyword parameter parameter value type value format/description
ALGORITHM "algorithm" String Method for setting routes in a OVXBigSwitch: "manual" or "spf"
BACKUPS "backup_num" Byte Number of backup paths associated with a virtual link or route
CTRLURLS "controllerUrls" List String="proto:host:port" where proto is usually "tcp"
DPID "dpid" Long DPID of a physical network switch
DPIDS "dpids" List One or more DPIDs of switches mapped to an OVXBigSwitch
DST_DPID "dstDpid" Long The DPID of the destination switch
DST_PORT "dstPort" Short The port on the destination switch
HOST "hostId" Integer UUID of a host
IS_BOOTED "isBooted" Boolean "true" if virtual network is initialized and "false" otherwise
LINK "linkId" Integer OVX-generated UUID of a virtual link
MAC "mac" String Host MAC address in colon-hex: "xx:xx:xx:xx:xx:xx"
NETADD "networkAddress" Integer The IP address block used in a network
NETMASK "mask" Short The CIDR value (1-30) of the network mask used with NETADD
PATH "path" List The physical path taken by a virtual link or route. A comma-separated list of links in the physical network: "SRC_DPID1/SRC_PORT1-DST_DPID2/DST_PORT2,SRC_DPID2/SRC_PORT3-DST_DPID3/DST_PORT4 …"
PORT "port" Short The port number of a switch port
PRIORITY "priority" Byte The priority (0-255) of a path associated with a link or route. Higher value is higher priority.
ROUTE "routeId" Integer OVX-generated UUID of a route
SRC_DPID "srcDpid" Long The colon-hex DPID of the source switch
SRC_PORT "srcPort" Short The port on the source switch
SWITCH_ROUTE "switch_route" - Not currently used
TENANT "tenantId" Integer The GUID of a virtual network
VDPID "vdpid" Long DPID of a virtual switch
VPORT "vport" Short The port number of a virtual switch port


Notations

We use several notations to describe the API syntax.

A keyword implicitly refers to a parameter: value relation. Example: TENANT is equivalent to

"tenantId": some_int

Elements in braces refers to a map. Example: {DPID, PORT} implies a Map containing two entries:

{ "dpid": some_Long, "port": some_Short }

Elements in square-brackets implies a list of values of the type associated with the keyword. Therefore, [LINK] is:

[ int1, int2, ... intn ] 

Braces in square-brackets would then be a list of Maps. [{LINK, PRIORITY}] implies:

[
    { "linkId": int_1, "priority": byte_1 },
    { "linkId": int_2, "priority": byte_2 },
    ...
]

There are also some non-keyword formatted strings that we refer to:

  • String-VDPID – VDPID in colon-hex notation: “00:a4:23:05:xx:xx:xx:xx” (Includes ON.Lab OUI)
  • String-DPID – DPID in colon-hex notation: “xx:xx:xx:xx:xx:xx:xx:xx”
  • String-VIP – A virtual IP address in dotted decimal: “x.x.x.x”
  • String-PIP – A physical IP address in dotted decimal: “x.x.x.x”
  • String-LINK – the LinkId, in string or integral form, e.g. “1” or 1

Finally, we also include notations closer to JSON. For example {“switches”: [String-DPID]}, would be a map keyed on the string “switches”, with a list of DPID strings as the value:

{
    "switches": [
        "00:a4:23:05:00:00:00:04", 
        "00:a4:23:05:00:00:00:03", 
        "00:a4:23:05:00:00:00:02",
        "00:a4:23:05:00:00:00:01"
    ]
} 


API Syntax

Monitoring API Parameters and Responses
Name Parameters Result Value Comments
getPhysicalTopology {"switches": [String-DPID], "links": [{LINK, "dst", "src"}]} Values for "src" and "dst" take form {PORT, DPID}
listVirtualNetworks [TENANT]
getVirtualTopology TENANT {"switches": [String-DPID], "links": [{LINK, "dst" ,"src", TENANT]} Values for "src" and "dst" take form {PORT, DPID}
getVirtualSwitchMapping TENANT {String-VDPID: {"switches": [String-DPID], "links": [String-LINK]}} [String-LINK] is a list of Integers
getVirtualLinkMapping TENANT {String-LINK: [String-LINK]} Key= virtual link ID as String and [String-LINK] is a list of physical link IDs as Integers
getVirtualHosts TENANT [{VDPID,VPORT,MAC,HOST}] Each entry in the list is a host's virtual represeantation
getPhysicalSwitchPorts DPID [PORT]
getPhysicalHosts [{HOST,DPID,PORT,MAC}] Each entry in the list is a host's physical representation
getSubnet TENANT String String=network/mask: "x.x.x.x/y"
getVirtualFlowtable TENANT,VDPID {String-VDPID: [FlowMod]} FlowMod is a field:value map of a OVXFlowMod message
getPhysicalFlowtable DPID {String-DPID: [FlowMod]} FlowMod is a field:value map of a OVXFlowMod message
getVirtualAddressMapping TENANT {String-VIP: String-PIP}
getVirtualSwitchPorts TENANT,VDPID [VPORT]
Tenant API Parameters and Responses
Name Parameters Return Value Comments
addControllers TENANT, VDPID, CTRLURLS CTRLURLS
removeControllers TENANT, CTRLURLS CTRLURLS
createNetwork CTRLURLS, NETADD, NETMASK {TENANT, CTRLURLS, NETADD, NETMASK, IS_BOOTED}
createSwitch TENANT, DPIDS, DPID {VDPID, DPIDS, TENANT}
createPort TENANT, DPID, PORT {DPID, PORT, VPORT, VDPID, TENANT}
SetOVXBigSwitchRouting TENANT, VDPID, ALGORITHM, BACKUPS {VDPID, DPIDS, ALGORITHM, BACKUPS, TENANT}
connectHost TENANT, VDPID, VPORT, MAC {VDPID, VPORT, MAC, HOST, TENANT}
connectLink TENANT, SRC_DPID, SRC_PORT, DST_DPID, DST_PORT, ALGORITHM, BACKUPS {LINK, PRIORITY, ALGORITHM, BACKUPS, PATH, TENANT} Value for PATH is [{SRC_DPID, SRC_PORT, DST_DPID, DST_PORT}] (Each entry is a physical link)
setLinkPath TENANT, LINK, PATH, PRIORITY {LINK, PRIORITY, ALGORITHM, BACKUPS, PATH, TENANT} Value for PATH is [{SRC_DPID, SRC_PORT, DST_DPID, DST_PORT}] (Each entry is a physical link)
connectRoute TENANT, VDPID, SRC_PORT, DST_PORT, PATH, PRIORITY {VDPID, SRC_PORT, DST_PORT, PRIORITY, ROUTE, PATH, TENANT} Value for PATH is [{SRC_DPID, SRC_PORT, DST_DPID, DST_PORT}] (Each entry is a physical link)
removeNetwork TENANT null
removeSwitch TENANT, VDPID null
removePort TENANT, VDPID, VPORT null
disconnectHost TENANT, HOST null
disconnectLink TENANT, LINK null
disconnectRoute TENANT, VDPID, ROUTE null
startNetwork TENANT {TENANT, CTRLURLS, NETADD, NETMASK, IS_BOOTED}
startSwitch TENANT, VDPID {VDPID, DPIDS, TENANT}
startPort TENANT, VDPID, VPORT {DPID, PORT, VPORT, VDPID, TENANT}
stopNetwork TENANT {TENANT, CTRLURLS, NETADD, NETMASK, IS_BOOTED}
stopSwitch TENANT, VDPID {VDPID, DPIDS, TENANT}
stopPort TENANT, VDPID, VPORT {DPID, PORT, VPORT, VDPID, TENANT}

Examples