Skip to end of metadata
Go to start of metadata

DRAFT

Description

We are transitioning the API to JSON from XMLRPC. The API syntax may change in some areas and therefore this document is intended to details these changes.

JSON-RPC API

Wire protocol is given below.

Command Name

Description

getSliceList

Fetches the list of slices configured at the FlowVisor

createSlice

Creates the specified slice

updateSlice

Modifies the slice with the supplied information.

removeSlice

Removes a slice

getSliceInfo

Fetches slice attributes such as controller url, email, etc

getSliceStats

Obtains the per slice counter for drop, send and receive packets.

updatePasswd

Changes a slice password

updateAdminPasswd

Changes the admin (ie. fvadmin) password

getDatapathStats

Returns number of packets received, send to and drop by the classifier associated to this switch

getDatapathFlowDB

Returns the flow rules that have been pushed to a dpid

getFlowSpace

Returns the flowspace (potentially per slice) defined at the FlowVisor

removeFlowSpace

Given a FlowVisor flowentry id, remove it.

addFlowSpace

Create a FlowVisor flowentry given a dpid, priority, match parameters and slice permission (action list)

updateFlowSpace

Given a dpid, priority, match, action list, replace flowentry at id id.

getDatapaths

returns a list of dpids seen by the FlowVisor

getDatapathInfo

Given a dpid, returns the features advertised by the switch

getLinks

Returns the set of switch connections discovered by FlowVisor

ping

Returns a pong with the original message msg

registerCallback

Registers a callback, which will be called if the topology changes

unregisterCallback

removes all or a specific callback set by this user

setFloodPerm

Sets the flood permission for a slice forslice. If no dpid is passed then this slice has flood permission for all dpids.

getFloodPerm

Get the flood permission for a given dpid. If no dpid return the flood permission for the default case.

setLoggingFacility

Sets the logging facility

getLoggingFacility

Gets the logging facility.

setLoggingIdent

Sets the logging identifier.

getLoggingIdent

Gets the logging identifier.

setFlowTracking

Enables/Disables flow tracking

getFlowTracking

Returns the status of flow tracking.

setStatsDescription

Enables/Disables statistics description field translation to a human readable format

getStatsDescription

Returns the status of stats description switch.

setDropPolicy

Sets the drop policy to policy ('exact' or 'rule') for slice slicename

getDropPolicy

Get the drop policy for slice *slicename

setRecvLLDP

Sets whether slice slicename receives all lldp messages.

getRecvLLDP

Get the lldp spam status for slice *slicename

Wire Protocol

Basic Notation

The descriptions below use the following shorthand notations for JSON
values. Additional notation is presented later.

<string>

A JSON string.

<id>

A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.

<boolean>

A JSON true or false value.

<number>

A JSON number.

<integer>

A JSON number with an integer value, within a certain range
(currently -2**63...+2**63-1).

<method>

A method from the table given above

<args>

An object of key/value JSON types that serve as arguments to a method.

<result>

Any valid combination of JSON types.

Getting Started

HTTP POST must be used to invoke JSON-RPC methods, GET will not work.

Request: HTTP POST to /flowvisorservice-v1

Question

Icon

Do we want to use 'flowvisorservice-v1'? In my opinion we may need (someday) to provide a significantly different service or some orthogonal API.

Icon

The 'params' field may be omitted.

Response:

Icon

The 'result' must not exist if there has been an error. Conversely, 'error' must not exist if there has not been an error.

The errorobj has the following structure:

Methods

It is assumed here that all input to methods will take the form of a request object. Therefore the 'method' field will be filled with the actual method name and the 'params' will take the arguments to this method. In a similar manner all response will be of the form of a response object. In the following, the 'results' and 'params' fields are explained using JSON schema while the remaining parts of the objects are shown for completeness.

getSliceList

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-1024

Unknown Error

An unknown error occurred.

createSlice

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Duplicate Slice

A slice with this host port pair already exists.

-8

Illegal Name

An invalid slice name was provided.

-16

Illegal email

The email address provided is invalid.

-32

Illegal Policy

The drop policy provided is invalid.

-1024

Unknown Error

An unknown error occurred.

updateSlice

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Duplicate Slice

A slice with this host port pair already exists.

-8

Illegal Name

An invalid slice name was provided.

-16

Illegal email

The email address provided is invalid.

-32

Illegal Policy

The drop policy provided is invalid.

-1024

Unknown Error

An unknown error occurred.

removeSlice

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown id

The given id was not found.

-1024

Unknown Error

An unknown error occurred.

getSliceInfo

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown slice

The given slice name was not found.

-1024

Unknown Error

An unknown error occurred.

getSliceStats

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown slice

The given slice name was not found.

-1024

Unknown Error

An unknown error occurred.

getDatapathStats

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown datapath

The given datapath name was not found.

-1024

Unknown Error

An unknown error occurred.

getDatapathFlowDB

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown datapath

The given datapath name was not found.

-8

Flow tracking disabled

Flow tracking is not enabled.

-1024

Unknown Error

An unknown error occurred.

getFlowSpace

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown slice

The given slice name was not found.

-1024

Unknown Error

An unknown error occurred.

removeFlowSpace

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown id

The given id was not found.

-1024

Unknown Error

An unknown error occurred.

addFlowSpace

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown slice

The given slice name was not found.

-8

Denied Permission

Cannot apply the given permission to the slice.

-1024

Unknown Error

An unknown error occurred.

updateFlowSpace

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown slice

The given slice name was not found.

-8

Denied Permission

Cannot apply the given permission to the slice.

-1024

Unknown Error

An unknown error occurred.

getDatapaths

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-1024

Unknown Error

An unknown error occurred.

getDatapathInfo

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-4

Unknown datapath

The given datapath name was not found.

-1024

Unknown Error

An unknown error occurred.

Request

Response

Errors

code

message

meaning

-1

Permission denied

Access was denied to FlowVisor.

-2

Database error

The internal db was not available.

-1024

Unknown Error

An unknown error occurred.

3 Comments

  1. Hi I have a question. What is the "id" field accompanied in each RPC for? i.e. What is it supposed to identify?

    Thanks. 

  2. Hi Lin, 

    This document is a proposal and will probably change before it is actually implemented. The id is used to identify the transaction and therefore allow multiple threads to process request more easily. 

  3. Hi Ali,
    I am running Flowvisor proxy and I want to send JSOR-RPC from another machine to list-slices. I used curl as following:
    curl -d '{"method":"list-slices"}'  http://flowvisor-host-ip:8081
    I got 'Empty reply from server' respond and when I looked at Flowvisor, it is giving me:
    :WARN::javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection?
    I looked at JettyServer class where it starts the Jetty server and I can see it is setting up an ssl-connection.
    So how do I communicate with the JSON API in Flowvisor? And is there SSL setup I need to be aware of?
    I couldn't find much of information from this page
    Thanks,
    Murad