XML-RPC is a remote procedure call that allows software running on different operating systems or different environments to make procedure calls over the Internet. It uses HTTP as the transport and XML as the encoding. XML-RPC is designed to be a simple as possible, while allowing complex data structures to be transmitted, processed and returned. Only a few basic datatypes are supported so it's not equivalent to most other RPC systems such as CORBA.
Traditionally to change system configuration parameters from a remote host, the user needed to create a configuration file on the host and transfer it to the Telestra platform. This mechanism has a number of disadvantages. Most notable, it requires the user to have an intimate knowledge of the Telestra file system structure, configuration file formats, and organization of the running system.
A better mechanism for managing various Telestra operations is to have a well defined interface between the host and Telestra. This interface is defined by XML-RPC and has the following advantages over the traditional mechanism:
The telestra command-line tool uses XML-RPC interfaces to let you control the Telestra servers from the Unix shell. The telestra command takes the name of a subcommand as its first argument. If the subcommand requires arguments, they are supplied after the subcommand. (If you're familiar with the CVS or SVN commands, they have a similar structure.)
If no subcommand is provided, the model status subcommand is executed.
If you remember only one subcommand, remember this one: telestra help will print a list of the available subcommands.
The location of the script can be found at /usr/local/asti/bin/telestra. The current list of subcommands is:
Legal commands are:
help: Display list of available commands
hla: View/modify HLA settings
hla-backchannel: View/modify HLA backchannel settings
hla-backchannel-signal: View/modify HLA backchannel signal settings
hla-join: Join HLA federation
hla-resign: Resign from HLA federation
hla-rti: Display RTI settings
hla-statistics: Display values of HLA counters
hla-status: Display status of HLA subsystem
model-load: Load default model on Telestra machine
model-select: Select a new default model for a particular user
model-start: Start model running
model-status: Display status of Telestra machine
model-stop: Stop model
reboot: Reboot system
shutdown: Shut down system
Examples:
# Prints list of models telestra model-list # Deletes a model belonging to "mbvuser" telestra model-delete mbvuser model1
You can use the --host setting to specify the hostname of the Telestra server to act upon. If the --host setting is not supplied, the script checks for the TELESTRA environment variable, and uses the value of this variable if it's set. This can be used to avoid having to retype --host repeatedly when issuing a series of commands. The following code can be used to set the host for any Telestra on the network:
telestra --host=# The syntax of setting environment variables depends upon the shell you use. # The following syntax is correct for sh/bash-derived shells. export TELESTRA= # Display system status telestra # Stop the currently running model telestra model-stop
If the environment variable isn't set, the default host used is "localhost".
Telestras currently support about 20 different XML-RPC methods. The list of methods will vary based on your Telestra software version. Rather than including them all, the interface can be found at "http://<telestra-ip-address>/test/rpc". You can point a web browser at this URL to get a formatted list of the methods that exist for your software version. The list will include the parameters of each method and a short description of each one.
The methods are currently grouped into five sections based on their functionality:
XML-RPC works by creating a small XML document that contains the name of a method to be called and the arguments to the method. This chunk of XML is then sent to a server using HTTP, the same protocol used by web browsers. The server processes the request and returns the results as the HTTP response.
For example, there's a service that returns the current time via XML-RPC located at http://time.xmlrpc.com/RPC2. It takes three lines of Python code to call it:
user@telestra: ~/$ python
Python 2.4.2 (#2, Sep 30 2005, 21:19:01)
>>> import xmlrpclib
>>> s = xmlrpclib.Server('http://time.xmlrpc.com/RPC2')
>>> s.currentTime.getCurrentTime()
<DateTime u'20060310T14:52:12 at -481d7114>
>>>
Watching the HTTP transaction going over the network, you would see the following traffic. First, the client sends the request to the server:
POST /RPC2 HTTP/1.0 Host: time.xmlrpc.com User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com) Content-Type: text/xml Content-Length: 120 <?xml version='1.0'?> <methodCall> <methodName>currentTime.getCurrentTime</methodName> <params></params> </methodCall>The server then returns the result of the call:
HHTP/1.1 200 OK
Content-Length: 183
Content-Type: text/xml
Date: Fri, 10 Mar 2006 19:54:27 GMT
Server: UserLand Frontier/9.0.1-WinNT
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<dateTime.iso8601>20060310T14:54:27</dateTime.iso8601>
</value>
</param>
</params>
</methodResponse>
For more information about XML-RPC, see "Programming Web Services with XML-RPC" by Simon St. Laurent, Joe Johnston, Edd Dumbill, O'Reilly, 2001, or "XML-RPC HOWTO" by Eric Kidd at http://tldp.org/HOWTO/XML-RPC-HOWTO/index.html.
For example, rebooting a Telestra is simple (example in Python):
s = xmlrpclib.Server('http://telestra.example.com/test/rpc')
s.telestra.reboot()
Most methods that perform an action return a string as their result. The result is the string 'ok' if there were no problems, or a message describing any problems that occurred. This message can usually be printed out to help a user figure out what's going wrong.
All of the following examples use Python.
In this example, we set some properties of a UDP host interface and then reload the model so that it will use the new property values.
s = xmlrpclib.ServerProxy('http://192.42.172.62/test/rpc')
s.host.set_tx('/Assets/Telestra/UDP_RX', '192.168.100.130', 12001)
path, owner = s.model.get_current()
s.model.load(owner)
This example sets the DIS packet address and the Site ID, and restarts the radio subsystem to make the new configuration active.
s = xmlrpclib.ServerProxy('http://192.42.172.62/test/rpc')
s.radio.dis.set_config('DIS', '192.42.172.255:53000:0', 'DIS_Site', 6)
time.sleep(1)
import xmlrpclib
s = xmlrpclib.ServerProxy('http://192.42.172.62/test/rpc')
# Upload a model present on host box. Say,
model_path = '/home/usera/testmodel.tgz'
## Read contents of .tgz file containing model
model_path = '/home/usera/testmodel.tgz'
data = open(model_path, 'rb').read()
## Upload the model stored on host box onto the Telestra, with model name 'sample_model'
print s.model.load('sample_model', 'mbvuser')
print s.model.set_default('sample_model', 'mbvuser')
print s.model.stop()
print s.model.start()
print s.model.get_current()