Introduction
SOS has been designed such that all configuration and interaction with the service can be done through a single point of contact -- namely the controller. The controller is the Floodlight OpenFlow controller outfitted with a special SOS module. All interaction is done over a REST API, which uses HTTP to facilitate high-level and well-defined data push and fetch.
By default, the SOS controller’s REST API runs at the controller’s IP on TCP port 8080. An HTTP client can be used to leverage the API. The popular utility curl is used throughout this document as an example HTTP client. For more information on curl, please refer to curl’s documentation. The following is a general example on how to use curl:
curl http://<controller-ip>:<tcp-port>/<uri-path> -X <http-command> -d ‘<data-string>’
where <controller-ip> is the IP address of the SOS controller
<tcp-port> is the TCP port on which the REST server is running
<uri-path> is the URI of the API
<http-command> is the HTTP command to use
<data-string> is the (optional) data to send to the API
Specific examples of this generalized form will be provided for each SOS API discussed.
SOS REST API
The SOS controller has the following APIs defined to perform common SOS operations:
| Operation | API (<uri-path>) | HTTP Command (<http-command>) | JSON Input Data (<data-string>) | JSON Data Returned | About |
|---|---|---|---|---|---|
| Configure SOS parameters | /wm/sos/config/json | POST or PUT | '{ "parallel-connections" : "<integer>", "buffer-size" : "<integer>", "queue-capacity" : "<integer>", "hard-timeout" : "<integer>", "idle-timeout" : "<integer>" }'
| Modify the running configuration of SOS. User need to supply all data – only those parameters to set/change. <integer> should be replaced with a zero or positive value. | |
| Add/remove SOS agent | /wm/sos/agent/add/json /wm/sos/agent/remove/json | POST or PUT POST or PUT | Specify the same data for add or remove. | ||
| Add/remove whitelist entry | /wm/sos/whitelist/add/json /wm/sos/whitelist/remove/json | POST or PUT POST or PUT | Specify the same data for add or remove. | ||
| Enable/disable SOS | /wm/sos/module/enable/json /wm/sos/module/disable/json | POST or PUT POST or PUT | '' | Specify an empty string as the data. An empty string is given by two single quotes, one after the other, e.g. ''. Do not use a double quote. | |
| Query SOS status | /wm/sos/status/json | GET | N/A | Omit -d parameter. Returns whether or not the agents are ready to accept another transfer. At present, each agent is allowed at most one transfer at a time. This can be used to detect when one transfer is "cleaned up" and the system is ready for another. | |
| Get statistics | /wm/sos/stats/json | GET | N/A | Omit -d parameter. Query past and present statistics. Does not include performance evaluation of transfers, although it will in the near future. |