RestConsole
From OpenSimulator
(→About) |
(→Syntax) |
||
| Line 19: | Line 19: | ||
Return: (XML) <ConsoleSession><SessionID></SessionID><Prompt></Prompt></ConsoleSession> | Return: (XML) <ConsoleSession><SessionID></SessionID><Prompt></Prompt></ConsoleSession> | ||
| − | Now we got the SessionID, which can be used to send a command. Use the SessionID as ID param, and send a POST again. | + | Now we got the SessionID, which can be used to send a command and to receive output. First, retrieve the console scrollback buffer. |
| + | Params: none | ||
| + | http://foo.bar:8002/ReadResponnses/<SessionID>/ | ||
| + | Return: (XML) <ConsoleSession><Line Number=x></Line></ConsoleSession> | ||
| + | The reply contains all lines currently in the buffer. Subsequent fetches will only retrieve new lines. The fetch will hold for up to 30 seconds if there is no data, then return an error. The client is expected to try again (polling). | ||
| + | |||
| + | Use the SessionID as ID param, and send a POST again. | ||
Params: ID, COMMAND | Params: ID, COMMAND | ||
http://foo.bar:8002/SessionCommand/ | http://foo.bar:8002/SessionCommand/ | ||
Revision as of 04:20, 6 September 2009
About
The REST console makes remote administration of the various OpenSim services possible.
The interface allows sending commands to the server and retrieving command output. Sending and receiving data is done through RESTful HTTP calls.
While sending is very straightforward, receiving is not. Receiving uses reverse HTTP, performing a long poll to a CAPS URI.
In order to make the protocol more efficient, the help functionality has been pushed to the client side. Rather than sending each keystroke to the server, only validated command lines are sent. To make this possible, the server sends a "connect burst" of data, which is the tree of allowed commands and their help information. This can be used by the client to create the "help" command output locally as well as provide command line help interactively.
The sample console client, OpenSim.ConsoleClient.exe, shows how this is done.
Syntax
We take the user service(http://foo.bar:8002) as example here. Startup the user service with:
mono OpenSim.Grid.UserServer.exe -console rest
First start a new session by sending a POST. Params: USER, PASS
http://foo.bar:8002/StartSession/
Return: (XML) <ConsoleSession><SessionID></SessionID><Prompt></Prompt></ConsoleSession>
Now we got the SessionID, which can be used to send a command and to receive output. First, retrieve the console scrollback buffer. Params: none
http://foo.bar:8002/ReadResponnses/<SessionID>/
Return: (XML) <ConsoleSession><Line Number=x></Line></ConsoleSession> The reply contains all lines currently in the buffer. Subsequent fetches will only retrieve new lines. The fetch will hold for up to 30 seconds if there is no data, then return an error. The client is expected to try again (polling).
Use the SessionID as ID param, and send a POST again. Params: ID, COMMAND
http://foo.bar:8002/SessionCommand/
Return: (XML) <ConsoleSession><Result></Result></ConsoleSession> If everything went well, the command should have been executed. Try another command.
When you want to close down the connection, send a POST again. PARAMS: ID
http://foo.bar:8002/CloseSession/
Return: (XML) <ConsoleSession><Result></Result></ConsoleSession> The session is closed, and you have to login again, when you want to send a command again.
Examples
In python:
