Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Sliceauthorityapi

Sliceauthorityapi

ProtoGeni Slice Authority

ProtoGeni Slice Authority

Overview

Each member of the federation runs a Slice Authority XMLRPC server. Since the members are running Emulab clusters, the SA is closely coupled to existing Emulab infrastructure. For example, the current implementation does not permit new users to be registered through the SA interface, but instead through the Emulab user interface.

Authentication

The certificates that researchers use to authenticate themselves to the local Slice Authority are generated by the local Emulab installation. Users request an encrypted (protected by a pass phrase) certificate via the Emulab web interface. The certificate is initially stored in the user's home directory, but can of course be copied anyplace the user likes. The certificate validates the user to all members of the federation, but the only SA that will grant it a slice credential is the local one.

API Documentation

The following sections (in conjunction with the standard ProtoGENI XMLRPC interface) describe the Slice Authority API. Where appropriate, we have used pythonese to describe arguments and return values.

GetCredential

Request a credential from the Slice Authority:

struct GetCredential();
struct GetCredential(credential, uuid, type);
struct GetCredential(credential, urn, type);

In its degenerate form, no arguments are provided, which indicates that the locally registered user is requesting a credential to access the rest of the Slice Authority API. In the second form, credential is the credential returned by the degenerate version, uuid is the uuid of an object, and type is limited to just Slice. In other words, the user is requesting a slice credential for an existing slice. The credential is granted only of the user is the original creator of the slice, or has been bound to the slice (see below).

The credential is returned as an XML document adhering to the schema in credential.rnc. Specifically, the target_gid of the credential is the slice GID and the owner_gid is the user requesting the credential. Thus, the credential can be used to manipulate the slice, but only by the same user.

Availability: supported in revisions 0 to 1.

Resolve

Lookup a UUID and return information about it:

struct Resolve(credential, uuid, type);
struct Resolve(credential, hrn, type);
struct Resolve(credential, urn, type);

where credential is the credential returned by the GetCredential() call above, uuid is the uuid of the object to be resolved, and type is one of Slice|User. The second form allows an object to be resolved by its human readable name (HRN).

The return value is an XML document representing a structure. When the type is Slice:

{
  "urn"  : "URN of the slice",
  "uuid" : "rfc4122 universally unique identifier",
  "creator_uuid" : "UUID of the user who created the slice",
  "creator_urn" : "URN of the user who created the slice",
  "gid"  : "ProtoGENI Identifier (an x509 certificate)",
  "component_managers" : "List of CM URNs which are known to contain slivers or tickets in this slice. May be stale"
}

When the type is User:

{
  "uid"  : "login (Emulab) ID of the user.",
  "hrn"  : "Human Readable Name (HRN)",
  "uuid" : "rfc4122 universally unique identifier",
  "email": "registered email address",
  "gid"  : "ProtoGENI Identifier (an x509 certificate)",
  "name" : "common name",
}

Availability: supported in revisions 0 to 1.

Register

Register a principle object, returning a new credential to manipulate that object later.

string Register(credential, hrn, type);
string Register(credential, urn, type);

where credential is the credential returned by the GetCredential() call above, hrn is a human readable name for the new slice, and type is limited to just Slice. The credential that is returned allows the caller to manipulate the new object.

As part of the process of registering a new slice, a new ProtoGENI Identifier (GID) is generated and registered at the ProtoGENI ClearingHouse.

Availability: supported in revisions 0 to 1.

Remove

Remove a principle object from the Slice Authority.

int Remove(credential, uuid, type);
int Remove(credential, urn, type);

where credential is the credential returned by the GetCredential() call above, uuid is the uuid of the object to be removed, and type is limited to just Slice.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

DiscoverResources

This is currently a placeholder; the Slice Authority simply calls out to the ProtoGENI ClearingHouse, invoking the ListComponents method.

list DiscoverResources(credential, rspec);

where credential is the credential returned by the GetCredential() call above.

The return value is a list of arrays, where each array contains the gid (certificate) of the manager. The URL and HRN can be extracted from the GID, but as a convenience the array includes these as well.

Availability: supported in revisions 0 to 1.

GetKeys

Get the SSH keys for the caller.

list GetKeys(credential);

where credential is the credential returned by the GetCredential() call above.

The return value is a list of SSH keys for the caller. These are the keys that the user has registered at the local Emulab via the web interface. The list is in a format that can be subsequently passed to Component Managers when instantiating a slice.

Availability: supported in revisions 0 to 1.

BindToSlice

Bind a local user to a slice so that the user may manipulate the slice. This call can be invoked by any user with a valid slice credential. The newly bound user can then request a slice credential using the GetCredential() above, providing the user with all of the same rights as the original slice creator.

int BindToSlice(credential, uuid);
int BindToSlice(credential, urn);

where credential is a credential credential returned by either the GetCredential() or Register() call above. and uuid is the uuid of the user to bind to the slice.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

RenewSlice

Request a change of expiration time for an existing slice.

string RenewSlice(credential, expiration);

where credential is the slice credential returned by the GetCredential() call above, and expiration is a string in valid RFC 3339 format.

If the RenewSlice operation succeeds, the expiration time of the slice is immediately updated, and a new slice credential indicating the new expiration is returned.

Upon failure, no change has been made.

Availability: supported in revision 1.

Implementation notes:

  • Existing slivers and tickets that might belong to the slice, are not affected. In order to extend the expiration of existing slivers, request a new slice credential using GetCredential() above, and then issue a RenewSlice() on each of the Component Managers where slivers exist. See the section on Renewing your Sliver in the tutorial for an example and more info.

Shutdown

Perform an emergency shutdown on a slice, by asking the SA (for that slice) to do an emergency shutdown. Operationally, the request is forwarded to the ClearingHouse which knows the full set of Component Managers. The call returns once the ClearingHouse is notified; the ClearingHouse will process the request asynchronously.

int Shutdown(credential);

where credential is a credential returned by the GetCredential() or Register() call above.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

GetVersion

int GetVersion();

Returns an integer corresponding to the revision of this API supported by the slice authority.

Availability: supported in revision 1 only.