ProtoGeni Test Scripts

A suite of command-line tools are now available for operation with ProtoGENI services. They act as an interim user interface, to provide a means to control ProtoGENI facilities until more sophisticated tools are available; and they are also a convenient debugging mechanism to test the emerging ProtoGENI components.

Before You Start

You can download a tarball of the test scripts at:

http://www.emulab.net/downloads/protogeni-tests.tar.gz

The source code for the tools can be found under the protogeni/test directory of the Emulab source distribution. They are also installed on the Emulab ops (users) node in /usr/testbed/protogeni/test

In order for the test scripts to run properly, you need to follow the setup instructions in the Tutorial.

Script Descriptions

Here are descriptions of several useful scripts you can use:

listcomponents.py

Requests a list of component managers from the clearinghouse. (This might also be useful as a basic test of the ProtoGENI infrastructure, as no privileges are required other than an account at a slice authority. Looking for correct output is a basic sanity check that the slice authority and clearinghouse are up and reachable, and the user's credentials are being accepted).

The component managers are described as a list of triples (HRN, URN and URL).

Example output

When run in the current federation (as of March, 2010), the output is:

utahemulab.cm[urn:publicid:IDN+emulab.net+authority+cm]: https://www.emulab.net/protogeni/xmlrpc/cm
wail.cm[]: https://www.schooner.wail.wisc.edu/protogeni/xmlrpc/cm
umlGENI.cm[urn:publicid:IDN+uml.emulab.net+authority+cm]: https://boss.uml.emulab.net/protogeni/xmlrpc/cm
cmulab.cm[]: https://boss.cmcl.cs.cmu.edu/protogeni/xmlrpc/cm
jonlab.cm[urn:publicid:IDN+jonlab.testbed.emulab.net+authority+cm]: https://myboss.jonlab.testbed.emulab.net/protogeni/xmlrpc/cm
myelab.cm[urn:publicid:IDN+myelab.testbed.emulab.net+authority+cm]: https://myboss.myelab.testbed.emulab.net/protogeni/xmlrpc/cm
ukgeni.cm[urn:publicid:IDN+uky.emulab.net+authority+cm]: https://www.uky.emulab.net/protogeni/xmlrpc/cm
primoGENI.cm[urn:publicid:IDN+primessf.net+authority+cm]: https://boss.primessf.net/protogeni/xmlrpc/cm
sparta.cm[urn:publicid:IDN+sparta.com+authority+cm]: https://host.referencecm.amp.emulab.net/protogeni/xmlrpc/cm

registerslice.py

Registers a new slice at the slice authority (and clearinghouse). If a slice with the same name exists already, it will be deleted first (assuming the user has sufficient privileges). The default slice name is "mytestslice", but that can be changed with the -n option.

Initially, the user who created the slice has full permission over it and no other users are granted any access, but the creator can set fine-grained permissions via delegation.

Example invocation

./registerslice.py -n exampleslice

createsliver.py

Creates and starts a sliver within a slice on a single component manager. If the slice does not already exist, it will be created. An RSpec filename can be specified to describe the resources to be requested; if none is given, then a sliver of a single virtual node will be created by default. If no RSpec is given, uses a simple one that grabs a single node. See our RSpec page and Request RSpec example pages for more ideas on how to create this RSpec.

Example invocation

./createsliver.py -n exampleslice mysliver.rspec

getticket.py

This performs a similar operation to createsliver.py, although the resource ticket is not actually redeemed (it is released after a short delay).

tuntest.py

This utility creates two slivers, on the two specified component managers. A single node is requested from each component manager, and a tunneled link is established between them. (Note that this is an iterative process; it is not possible to construct a topology like this by createsliver.py alone, since the link properties depend on the physical topology, which is not known in advance.)

Example invocation

./tuntest.py -n exampleslice utahemulab ukgeni

slicestatus.py

sliverstatus.py

These two commands query the status of a slice or sliver from a component manager. The status consists of a list of nodes, and shows the UUID and status ("ready" or "notready") of each one.

Example invocation

./slicestatus.py -n exampleslice

deletesliver.py

This is the counterpart to the createsliver.py utility above, and releases resources that were allocated there.

Example invocation

./deletesliver.py -n exampleslice

unregisterslice.py

UnRegister an existing slice at the slice authority (and clearinghouse). The default slice name is "mytestslice", but that can be changed with the -n option.

Example invocation

./unregisterslice.py -n exampleslice

slice.py

This is a utility for performing distributed operations on all nodes in all slivers within a slice. The operations currently available are "exec <command>", "install <file>", and "list".

Example invocation

./slice.py -n exampleslice install mypackage.tar.gz exec './myprogram > /tmp/myoutput'

Additional Options

Each of the utilities accepts many options besides those shown above. The "-h" (equivalently, "--help") option can be specified to request a list of all options, but generally the following are available:

-f file

Read the user's SSL certificate from "file". By default, "~/.ssl/encrypted.pem" is used; this should have been created through the Emulab WWW interface. (Another way to specify this file is to give it in the environment variable PROTOGENI_CERTIFICATE.)

-p file

Read the corresponding SSL passphrase from "file". This would have been specified through the same WWW interface at the time the certificate was created. (Another way to specify this file is to give it in the environment variable PROTOGENI_PASSPHRASE.)

-c file

Read the user's credentials (to be presented to the slice authority) from "file". By default, no file is read, and the credentials are obtained directly from the slice authority (initial authentication is performed with the SSL certificate, as above).

-s file

Read the slice credentials from "file". By default, credentials will be obtained directly from the slice authority, although this will work only for the creator of the slice. All other users should request delegated credentials from the creator (or another privileged user), and present them by invoking this option.

-n slicename

Specify the slice to be used. The default is "mytestslice", although obviously collisions will be less likely if the user invents a better name.

-m url

Specify the URL of the component manager to be used. By default, the test scripts attempt to contact a CM running on the same host as the authority that issued the user's certificate.

-r optionfile

Read configuration commands from "optionfile". This might be necessary for advanced operations (e.g. overriding the choice of component manager to connect to).

-d

Turn on debugging output. This is probably more verbose than is useful for most purposes, but might come in handy if things are going mysteriously wrong.