• How to set up the OMF AM's slicemgr XML-RPC interface.
  • Install and configure an XMPP server (optional)
  • Configuring the aggregate manager
  • Dry-run mode
  • The XML-RPC API
    • • Overview
      • slicemgr.createSlice(slice_name)
      • slicemgr.addResource(slice_name, resource_name)
      • slicemgr.removeResource(slice_name, resource_name)
      • slicemgr.deleteSlice(slice_name)
      • NOTES:

How to set up the OMF AM's slicemgr XML-RPC interface.¶

The slicemgr XML-RPC interface is an OMF Aggregate Manager (AM) service offered over HTTP. The AM creates an HTTP server (on port 5053), and the XML-RPC interface is accessible at the URI /slicemgr of this server. The slicemgr service creates and removes XMPP PubSub nodes on the testbed's XMPP server to cater for creation and deletion of slices, and for the addition and removal of resources from or to a slice.

Instructions for installing and configuring the AM with the slicemgr service enabled are below, followed by instructions to set up dry-run mode for testing.

Install and configure an XMPP server (optional)¶

To use the slicemgr interface, the AM must be installed, and an XMPP server must be installed somewhere that is accessible to the machine running the AM (but not necessarily the same machine). OMF is tested with the OpenFire XMPP server. Installation notes for installing an OpenFire server for OMF can be found here. If you just want to test the slicemgr XML-RPC interface itself, you can configure it in dry-run mode. This mode simulates the creation and removal of XMPP PubSub nodes, so it presents the client with an identical-looking behaviour, but it never even tries to connect to an XMPP server, so it can be tested in isolation without an XMPP server.

Once the OpenFire server is created, log in to its control panel and create a new user for the Aggregate Manager to use. The AM is configured to connect as user 'aggmgr' with password '123' by default.

Configuring the aggregate manager¶

• add this line to your /etc/apt/sources.list:

deb http://pkg.mytestbed.net/ubuntu testing/

• apt-get update
• apt-get install omf-aggmgr-5.3
• enable the service by creating the following symlink:

cd /etc/omf-aggmgr-5.3/enabled
ln -s ../available/slicemgr.yaml

• Modify the configuration file called /etc/omf-aggmgr-5.3/available/slicemgr.yaml to set up the XMPP server (set this to your XMPP server's IP address or hostname). Also modify the 'username' and 'password' attributes in slicemgr.yaml to match the ones you used when you installed the XMPP server, above. (If you just want to test with dry-run mode, the setting of these attributes in the .yaml file don't matter.)
• Execute /etc/init.d/omf-aggmgr-5.3 restart. Run this whenever you edit a .yaml file to apply the changes
• The AM listen port is set in the file /etc/omf-aggmgr-5.3/gridservices.cfg
• The location of the AM's log file is specified using the file /etc/omf-aggmgr-5.3/def_gridservices_log.xml. By default the log is stored in /var/log/omf-aggmgr-5.3.log.

Once the AM is running, the log file will display debug messages from all services that are enabled, which should just be the slicemgr service if the above instructions were followed. Each time a slice is created or deleted, and each time a resource is added to or removed from a slice, the slicemgr service will write a DEBUG message to the log describing the actions it has taken.

Dry-run mode¶

To enable dry run mode:

• Edit the configuration file called /etc/omf-aggmgr-5.3/available/slicemgr.yaml and uncomment the line:

#  dry-run: true

In dry-run mode, the log still records the actions that would have been taken by the slicemgr service in normal mode. However, dry-run mode does not require an XMPP server to be installed, since it does not attempt to execute its normal actions.

The XML-RPC API¶

The API is available below or as a text file here: slicemgr-1.txt

Overview¶

The slicemgr service provides an XML-RPC bridge to an OMF testbed's
XMPP server. It provides interfaces to add and remove PubSub nodes on
the XMPP server. The service only allows manipulation of PubSub nodes
relating to the management of the resources of a slice.

The OMF PubSub nodes are organized as a tree (although XMPP does not
provide any support for hierarchical node structures). A diagram of the
OMF PubSub node tree can be found here:

http://omf.mytestbed.net/wiki/omf/OMFControlPlanetLab

The top-level node is always called 'OMF'. Underneath the OMF node is
a node called OMF/system node, which is used for testbed management
functions, and is not accessible via this XML-RPC interface. Alongside
the OMF/system node are any number of siblings, each of which
corresponds to a PlanetLab slice.

For instance, a slice named 'foo' will have a PubSub node called
'OMF/foo'.

All slices will have a PubSub child node named like
'OMF/<slice_name>/resources'. The children of
'OMF/<slice_name>/resources' are PubSub nodes that correspond to the
slivers or resources of the slice. Experiments executed on a slice
will generate their own PubSub nodes under
'OMF/<slice_name>/<experiment_name>'.

This XML-RPC interface allows for creating and removing the following
PubSub nodes:

- OMF/<slice_name>
- OMF/<slice_name>/resources
- OMF/<slice_name>/resources/<resource_name>

The 'OMF' and 'resources' components of these PubSub node names are
literal; the terms in angle brackets '<','>' are substituted with the
actual name of the slice and the resource.

NOTE: the PubSub node names are case sensitive.

NOTE: the API does not yet support authentication. Current proposal
is to handle SSL/TLS symmetric authentication using a reverse HTTP
proxy such as lighttpd.

The available XML-RPC interfaces are described below. They are
provided by the OMF Aggregate Manager, mounted on the /slicemgr URI.

slicemgr.createSlice(slice_name)¶

IN:
slice_name -- string -- name of the slice to be created

Description: Creates the top-level PubSub nodes for a new slice. For
instance, if slice_name is 'foo', then the following two nodes will be
created:

- OMF/foo
- OMF/foo/resources

If either of these nodes already exist then the RPC succeeds as normal
(no indication is returned to the client that the node already
existed). If the slice_name is 'system' (or 'SYSTEM', or 'SYStem', or
'sYStem", etc.) then the RPC fails with fault code 1.

OUT:
struct
result => "OK" (if the call succeeded)
name => sliceid -- string -- e.g. "OMF/foo"

slicemgr.addResource(slice_name, resource_name)¶

IN:
slice_name -- string -- name of the slice
resource_name -- string -- name of the new resource

Description: Add a new resource under the slice with the given
slice_name. The slice should already have been created using
slicemgr.createSlice. If slice_name is 'foo' and resource_name is
'onelab10.inria.fr', then the following PubSub node will be created:

- OMF/foo/resources/onelab10.inria.fr

If the node already exists then the RPC succeeds as normal (no
indication is returned to the client that the node already existed).
If the slice_name is 'system' (or 'SYSTEM', or 'SYStem', etc.), then
the RPC fails with fault code 1.

OUT:
struct
result => "OK" (if the call succeeded)
slice => sliceid -- string -- e.g. "OMF/foo"
resource => resourceid -- string -- e.g. "OMF/foo/onelab10.inria.fr"

slicemgr.removeResource(slice_name, resource_name)¶

IN:
slice_name -- string -- name of the slice
resource_name -- string -- name of the resource

Description: Removes the resource called resource_name from the slice
called slice_name. If the slice_name is 'foo' and the resource name is
'onelab10.inria.fr', then the following PubSub node will be removed:

- OMF/foo/resources/onelab10.inria.fr

If this PubSub node does not exist then the call succeeds silently (no
indication is given to the client that the node did not exist
already). If the slice_name is 'system' (or 'SYSTEM', or 'SYStem',
etc.), then the RPC fails with fault code 1.

OUT:
struct
result => "OK" (if the call succeeded)
slice => sliceid -- string -- e.g. "OMF/foo"
resource => resourceid -- string -- e.g. "OMF/foo/onelab10.inria.fr"

slicemgr.deleteSlice(slice_name)¶

IN:
slice_name -- string -- name of the slice to delete

Description: Deletes the slice called slice_name. If the slice_name
is 'foo' then the following PubSub nodes will be removed:

- OMF/foo
- OMF/foo/resources
- OMF/foo/resources/*

The wildcard "OMF/foo/resources/*" means that all PubSub nodes
corresponding to resources for slice 'foo' will also be removed by
this RPC.

If slice_name does not refer to an existing slice then this RPC
succeeds silently (no indication is given to the client that the node
did not exist already). If the slice_name is 'system' (or 'SYSTEM, or
'SYStem', etc.) then the RPC fails with fault code 1.

OUT:
struct
result => "OK" (if the call succeeded)
slice => sliceid -- string -- e.g. "OMF/foo"
resources => resource_list -- array -- an array of the
resource nodes removed.

NOTES:¶

• This document describes the first prototype implementation of the
  XML-RPC interface to the slice/resource creation functions. The fact that
  error indications are not returned for attempts to add existing
  slices/resources or remove non-existing slices/resources is an artefact of the
  current implementation environment and should be rectified in a
  subsequent revision.

---