Table of Contents
...
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:
...
| Operation | API (<uri-path>) | HTTP Command (<http-command>) | JSON Input Data (<data-string>) | JSON Data Returned | About | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Configure parameters | /wm/sos/config/json | POST or PUT | '{ "parallel-connections" : "<integer>", "buffer-size" : "<integer>", "queue-capacity" : "<integer>", "hard-timeout" : "<integer>", "idle-timeout" : "<integer>" }' | '{ "code" : "<integer>", "message" : "<string> }' | Modify the running configuration of SOS. User need not supply all data – only those parameters to set/change. Input data is a JSON object of key:value pairs. <integer> should be replaced with a zero or positive value. Returns 0 code for success; all others indicate failure. | ||||||||||||||
| Retrieve parameters | /wm/sos/config/json | GET | N/A | '{ "parallel-connections" : "<integer>", "buffer-size" : "<integer>", "queue-capacity" : "<integer>", "hard-timeout" : "<integer>", "idle-timeout" : "<integer>" }' | Set of parameters as they are configured. | ||||||||||||||
| Add/remove agent | /wm/sos/agent/add/json /wm/sos/agent/remove/json | POST or PUT | '{ "ip-address" : "<string>", "data-port" : "<integer>", "control-port" : "<integer>", "feedback-port" : "<integer>" }' | '{ "code" : "<integer>", "message" : "<string> }' | Specify the same data for add or remove. Input data is a JSON object of key:value pairs. <string> should be replaced with a dotted-decimal IP address, e.g. 192.168.1.1. <integer> should be replaced with the corresponding port number. Returns 0 code for success; all others indicate failure. | Add/remove whitelist entry||||||||||||||
| Retrieve agents | /wm/sos/ | whitelist/addagent/json | POST or PUT | '{ "server-GET | N/A | '[ { "ip-address" : "<string>", " | servermac- | tcp-portaddress" : " | <integer><string>", " | clientdata- | ip-addressport" : " | <string><integer>", " | startcontrol- | timeport" : " | <string><integer>", " | stopfeedback- | timeport" : " | <string>" }''{ "code" : "<integer>", "messageactive-transfers" : [ "<string>" ] } ' Specify the same data for add or remove. Input data is a JSON object ]' | List of SOS agent objects. Includes list of active transfers. <string> is a dotted-decimal IP address, colon-delimited MAC address, and a UUID, respectively. |
| Add/remove whitelist entry | /wm/sos/whitelist/add/json /wm/sos/whitelist/remove/json | POST or PUT | '{ "server-ip-address" : "<string>", "server-tcp-port" : "<integer>", "client-ip-address" : "<string>", "start-time" : "<string>", "stop-time" : "<string>" }' | '{ "code" : "<integer>", "message" : "<string> }' | Specify the same data for add or remove. Input data is a JSON object of key:value pairs. <string> IP addresses should be replaced with a dotted-decimal IP address, e.g. 192.168.1.1. <integer> should be replaced with the corresponding port number. <string> date/time should be replaced with any valid date/time string or value. Note: Start/stop times are currently ignored. Returns 0 code for success; all others indicate failureor value. Note: Start/stop times are currently ignored. Returns 0 code for success; all others indicate failure. | ||||||||||||||
| Retrieve whitelist entries | /wm/sos/whitelist/json | GET | N/A | '[ { "server-ip-address" : "<string>", "server-tcp-port" : "<integer>", "client-ip-address" : "<string>" } ]' | List of whitelist entry objects. <string> is a dotted-decimal IP address. | ||||||||||||||
| Enable/disable module | /wm/sos/module/enable/json /wm/sos/module/disable/json | POST or PUT | '' | '{ "code" : "<integer>", "message" : "<string> }' | 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. GET not used for security/safety reasons.Returns 0 code for success; all others indicate failure. Returns 0 code for success; all others indicate failure. | ||||||||||||||
| Get module operating mode | /wm/sos/module/json | GET | N/A | '{ "enabled" : "<boolean>" }' | <boolean> is either true if enabled or false if disabled. | ||||||||||||||
| Query status | /wm/sos/status/json | GET | N/A | '{ "code" : "<integer>", "message" : "<string> }' | 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. Returns 0 code for ready; 6 for not ready; all others indicate failure. | ||||||||||||||
| Get statistics | /wm/sos/stats/json | GET | N/A | Non-trivial output. Gives agents, whitelist entries, active and past transfers, routes utilized, and more. | Omit -d parameter. Query past and present statistics. Does not include performance evaluation of transfers, although it will in the near future. |
...
After the network is configured, the agents should then be added to the controller, information about the transfer to conduct SOS on should be whitelisted in the controller, any SOS parameters should be tuned as desired, and lastly the controller should be checked to ensure the network is ready to handle the pending transfer. At this point, the transfer can be initiated.
...
Once the agents have been added, the transfer has been whitelisted, and the controller indicates the SOS network is ready to handle the transfer, the user can initiate the transfer using any means on the client machine. The assumption is that the underlying transport protocol used is TCP and that the client IP address, server IP address, and server TCP port are those indicated in the whitelisted entry.is ready to handle the transfer, the user can initiate the transfer using any means on the client machine. The assumption is that the underlying transport protocol used is TCP and that the client IP address, server IP address, and server TCP port are those indicated in the whitelisted entry.
 | It is important to remember that SOS is a transparent service. From a user's perspective, the transfer should be initiated from the client to the server as a normal transfer would be conducted. The transfer should not in any way be directed to/from the agent IP addresses – this will happen automatically for you. In order for SOS to properly detect and perform this redirection, the transfer must be initiated by the client IP to the server IP at the server TCP port as indicated in the whitelist entry configured above. |
|---|
Check Statistics
To get information about the transfer being performed, such as the agents chosen, the routes being used, etc. The statistics API can be used as follows:
...