Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Serviceimplementersguide

Serviceimplementersguide

Service Implementer's Guide

Service Implementer's Guide

This is a guide for projects implementing services in ProtoGENI slices (such as monitoring, measurement and instrumentation services), about how best to use the ProtoGENI APIs to hook in their services.

General Notes

Part of the job of the type of services envisioned will be to behave as an agent, invoking ProtoGENI operations on behalf of the user. The remainder of this document assumes familiarity with the basic ProtoGENI API -- please consult the Tutorial for an introduction.

Service Strategies

One effective technique for constructing higher level ProtoGENI services is to allow the user to allocate resources within a slice in the conventional fashion, and then provide tools which automatically augment the slice with additional software and/or additional GENI resources to provide new functionality. Please refer to the INSTOOLS project for an example of this strategy, with working source code.

Certificates and Credentials

Generally, each user should be responsible for managing his or her user certificate and corresponding private key. Your service software can assume that the user will provide both of these (as well as the passphrase to decrypt the key, when necessary). For example, the ProtoGENI test scripts assume both the certificate and the key are stored in the file $HOME/.ssl/encrypted.pem. Your code can do the same thing, or a reasonable equivalent.

However, credentials are often managed in a way that is transparent to the user. Given the certificate, it is possible to obtain a slice authority credential (and then any existing slice credentials) through the XMLRPC interface. This is generally a sensible default mode of operation, since your software can frequently obtain all the credentials required without further interaction with the user.

In certain cases (particularly when unusual credentials or delegation is involved), it will be impossible to obtain all relevant credentials automatically. Therefore, it is important to allow the user the option of supplementing (or replacing) the automatically retrieved credentials with others that are supplied manually, too.

Frequently Asked Questions

Is there a way to look up all the slices a user has activated at a particular CM?

Not directly, but a Resolve call at the user's slice authority will yield all slices created by that user. You could then iterate over all CMs of interest, asking for a Resolve on each slice name. Each one will give you the corresponding sliver, if it exists.

Is it possible to determine a user ID given only one of their credentials?

Yes. The owner field of the credential gives the ID of the principal to whom it belongs. See the protogeni/test/showcredential.py script for an example of how to find the owner of a credential.

Are there examples of the slice_urn, rspec, keys and credentials[] parameters to the CM CreateSliver and DeleteSlice operations, and examples of return values?

slice_urn is a string of the form:

    urn:publicid:IDN+emulab.net+slice+mytestslice

rspec is a string containing an XML document which might look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <rspec xmlns="http://www.protogeni.net/resources/rspec/0.1"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.protogeni.net/resources/rspec/0.1
http://www.protogeni.net/resources/rspec/0.1/request.xsd"
           type="request" >
      <node virtual_id="my-node"
            virtualization_type="emulab-vnode"
            exclusive="1">
        <node_type type_name="pc" type_slots="1"/>
        <interface virtual_id="control"/>
      </node>
    </rspec>

keys (if used) is an XMLRPC array of structs containing type and key members (both strings), e.g.:

    [{'type': 'ssh', 'key': 'ssh-rsa
AAAAB3NzaC1dc2EAAAABIwAAAQEA8jmEaclqDDUzNZf8PwEUlFDhgi0SkAwwmCWf96QDnUWbAqLkjhat
WF1zSbJaLEkGDGKutXgI33xibtEox8r8cz0ek+t8gxXo+19zz1W5FMw+FoEJxSX4ylTaFD4nFz1qNe6z
gWIngDZvafQDhP4XOJN5m8bjaMi5f5efR+0I/SE3VWVh0oF9Dg1pVtOuDYSK3k+xc70PkPErbGZKO/Pa
Gagbw0JFp7fYT1BCodhFa3o/z6kShU4bOdjZ/3ryq6BeGg0YCYiJ8DpvvK7/3u7/Xpf2ADGvjE2uxAnF
3CZpXG6DytATEapYcsKhkuok6uX9P5+IreZe0FNsKXAfJncatw== user at host'}]

where the above is shorthand for XMLRPC arrays and structs.

credentials in the most common case will simply be a list with one element (the slice credential). This will typically come directly from the SA, so the client does not need to generate it (and perhaps not even inspect it), but it will look like this:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <signed-credential>
     <credential xml:id="ref1">
      <type>privilege</type>
      <serial>12345</serial>
      <owner_urn>urn:publicid:IDN+emulab.net+user+gary</owner_urn>
      <target_urn>urn:publicid:IDN+emulab.net+slice+mytestslice</target_urn>
      <expires>2010-01-01T00:00:00</expires>
      <privileges>
       <privilege>
        <name>*</name>
        <can_delegate>1</can_delegate>
       </privilege>
      </privileges>
     </credential>
     <signatures>
      ---XML Signature elements (signatures and certificates) go here---
     </signatures>
    </signed-credential>

As far as responses go, the CreateSliver response (on success) is an XMLRPC struct with two members (sliver and manifest). The sliver member is a sliver credential, which looks almost identical to the slice credential example above except that the target_urn is a sliver URN instead of a slice URN, and it is signed by the CM instead of the SA. The manifest member looks like this:

    <rspec xmlns="http://protogeni.net/resources/rspec/0.1">
      <node virtual_id="geni1" virtualization_type="raw" exclusive="1"
         component_urn="urn:publicid:IDN+emulab.net+node+pc123"
         component_manager_urn="urn:publicid:IDN+emulab.net+authority+cm"
         hostname="pc123.emulab.net"
         sliver_urn="urn:publicid:IDN+emulab.net+sliver+1234" />
    </rspec>

See the docs for the specification of how the value is embedded in the XMLRPC methodResponse structure.

The return value for DeleteSlice is very simple, since it is just an indication of success or failure. The code element will be 0 on success, and non-zero otherwise (in which case output should be some descriptive string) -- again, see the ProtoGENI XMLRPC docs to see how code and value should be inserted into methodResponse.

If CreateSliver is called twice consecutively, are more resources added to the sliver, or is a new sliver created with new resources?

Actually, if a sliver already exists, a subsequent CreateSliver() call should fail with code GENIRESPONSE_REFUSED (7).

Why would the listcomponents script complain about an M2Crypto.SSL.Checker.WrongHost error?

This can indicate an incompatibility between certain versions of the ProtoGENI software and the M2Crypto Python library. Please consult the Host Name Mismatch errors page.

Is it possible to get information about which CMs my slivers currently exist on?

Yes. If you know which slice the slivers belong to, invoke a Resolve operation for that slice at the appropriate slice authority. The component_managers field in the return value will give you a list of CM URNs.

Note that this is considered informational only, not an absolute guarantee since this info can be stale (for any number of reasons).

How should I describe a slice spanning multiple CMs? Should all CMs be provided the complete rspec?

There are a number of possibilities. If you provide your whole request to a CM, it will just allocate the nodes tagged for that CM and give you a manifest with information added to those nodes. The only time it is necessary to give a CM a more complete view of your topology is when you are stitching CMs together (as with tunnels).

With a tunnel, you should send a request with nodes on both sides of the tunnel to both CMs. Usually, the easiest thing to do is create one large request and send it to everyone.

Further Information

Online Documentation

Contact Details

Questions about service implementation should be directed to the geni-dev@emulab.net mailing list. Archives of the list are also available.