Tue Sep 02 8:04pm MDT
Vers: 4.403 Build: 09/02/2014
2b2f8a7bd1c91fda4f8e5166

Emulab Tutorial: XMLRPC Interface to Emulab

Printable version of this document

Emulab Tutorial - XMLRPC Interface to Emulab

This page describes the XMLRPC interface to Emulab. Currently, the interface mainly supports experiment creation, modification, swapping, and termination. We also provide interfaces to several other common operations on nodes end experiments such as rebooting, reloading, link delay configuration, etc. This interface is a work in progress; it will improve and grow over time. If there is something missing you need, please send us email.

The Emulab XMLRPC server can be accessed via an SSL based server. You need to request a certificate from the Emulab website in order to use the SSL based server. Go to the "My Emulab" portion of the Emulab website, and click on the "Create SSL Certificate" link. You will be prompted for a passphrase to use to encrypt the private key. Once the key has been created, you will be given a link to download a text version (PEM format). Simply provide this certificate as an input to your SSL client.

The API is described in detail below. A demonstration client written in Python is also available that you can use on your desktop to invoke commands from the shell. For example:

    sslxmlrpc_client.py startexp batch=false wait=true proj="myproj" exp="myexp" nsfilestr="`cat ~/nsfile.ns`"
which says to create an experiment called "myexp" in the "myproj" project, swap it in immediately, wait for the exit status (instead of running asynchronously), passing inline the contents of nsfile.ns in your home directory on your desktop. By default, the client will contact the RPC server at boss.emulab.net, but you can override that by using the -s hostname option. For example:
    sslxmlrpc_client.py -s boss.emulab.net startexp ...
which would invoke the RPC server on boss.emulab.net. You will be prompted for your SSL passphrase.

The sslxmlrpc_client python program is a simple demonstration of how to use Emulab's RPC server. If you do not provide a method and arguments on the command line, it will enter a command loop where you can type in commands (method and arguments) and wait for responses from the server. It converts your command lines into RPCs to the server, and prints out the results that the server sends back (exiting with whatever status code the server returned).f You can use this client program as is, or you can write your own client program in whatever language you like. Remember to use the --cert= option to tell the demonstration client where to find your certificate. You will be prompted for the private key passphrase when it attempts to contact the server.

A more sophisticated client called script_wrapper.py provides a traditional command line interface to Emulab, using the SSL transport described above. The client should run on any machine that has Python installed. For example, to swap the myexp experiment in the testbed project in:

    script_wrapper.py --server=boss.emulab.net swapexp -e testbed,myexp in
Each command has its own --help option:
    script_wrapper.py swapexp --help
    
    swapexp -e pid,eid in|out
    swapexp pid eid in|out
    where:
         -w   - Wait for experiment to finish swapping
         -e   - Project and Experiment ID
         in   - Swap experiment in  (must currently be swapped out)
        out   - Swap experiment out (must currently be swapped in)
A complete list of Emulab commands available via the script wrapper is available with the --help command:
    script_wrapper.py --help
    Usage: wrapper [wrapper options] command [command args and opts]
    
    Commands:
        readycount   Get readycounts for nodes in experiment (deprecated).
        startexp     Start an Emulab experiment.
        savelogs     Save console tip logs to experiment directory.
        endexp       Terminate an experiment.
        eventsys_control Start/Stop/Restart the event system.
        batchexp     Synonym for startexp.
        node_list    Print physical mapping of nodes in an experiment.
        expinfo      Get information about an experiment.
        node_admin   Boot selected nodes into FreeBSD MFS.
        create_image Create a disk image from a node.
        delay_config Change the link shaping characteristics for a link or lan.
        modexp       Modify experiment.
        nscheck      Check and NS file for parser errors.
        swapexp      Swap experiment in or out.
        os_load      Reload disks on selected nodes or all nodes.
        portstats    Get portstats from the switches.
        link_config  Change interface parameters for a wireless link.
        node_reboot  Reboot selected nodes or all nodes in an experiment.
As a convenience, you can symlink script_wrapper.py to each of the commands listed above, and avoid having to type the wrapper name:
    ln -s script_wrapper.py swapexp

    swapexp --server=boss.emulab.net -e testbed,myexp in
This has already been done in users.emulab.net:/usr/testbed/bin, so each of the above commands is already on your path.

Server API

The API for the server is broken into several different modules that export a number of methods, each of which is described below. Each method is of the form (in Python speak):

    def startexp(version, arguments):
        return EmulabResponse(RESPONSE_SUCCESS, value=0, output="Congratulations")
The arguments to each method: The client specifies the proj and exp of the experiment he/she wants to swap, as well as the actual swap operation, in this case out. The response from the server is another hashed array (Python Dictionary) of the form:
  • code: An integer code as defined in emulabclient.py.
  • value: A return value. May be any valid data type that can be transfered in XML.
  • output: A string (with embedded newlines) to print out. This is useful for debugging and for guiding users through the perils of XMLRPC programming.
Unless specifically stated, the return value of most commands is a simple integer reflecting an exit code from the server, and some output to help you determine what went wrong. Otherwise, the return value is documented in each method description.

Finally, a quick note about the types accepted and returned by methods. Most methods will accept a real XML-RPC type and try to coerce a string into that type. For example, in python, passing True is equivalent to passing the string, "true". When returning data, the methods will prefer to return typed values, rather than formatted strings.