DETER Testbed API

The DETER API is really an interface with two sides, an outward facing side (the testbed API) that allows people to manage resources on the testbed and an inward facing side (the containers API) that coordinates the containers that make up an experiment environment. This document defines these interfaces and documents how to use them. It is a living document that will gain detail as the specification grows and implementations are put into service. At this point (July 2013) it is mostly a roadmap.

The testbed API is responsible for managing the following things:

Users

researchers

Projects

groups of related users, used to manage what users can see and do to other testbed resources

Experiments

a research environment that may be stored, edited, and realized on testbed resources

Resources

building blocks for experiments: computers, disk images, external access

The testbed API how users ask a DETER testbed to do things for it. It will generally be called from a more user-friendly front end, tuned to the user's experience and goals, such as the evoloving DETER Beginners Interface.

The containers API is used by the DETER control system to manage the resources that make up an experimental topology in progress. The goal of this API is to take raw resources inside the testbed that have been allocated using the testbed API, and configure them into a usable environment. Each logical element of an experiment (a computer, a router, etc.) is represented by a container which must be managed by DETER.

Managing a container consists of:

• Installing and configuring any virtualization software or configuring hardware
  • This involves translating from a more generic topology/configuration description into the setup for a specific container type
• Configuring and starting MAGI software necessary to connect to the experiment management system
• Exposing and using container-specific features to provide DETER services

We discuss the testbed API and then the containers API. Then we discuss some initial implementation details and present a roadmap for development.

User Features

A user is a researcher who uses the DETER testbed. They request testbed services and allocate testbed resources. Each call on the API is performed by a user. A user is identified by a string unique to DETER, teh username.

User Meta-data

In addition to the user identifier DETER keeps meta-data about all users. Currently that meta-data consists of:

• Projects the user is in (see below)
• Experiments the user owns (see below)
• A password to authenticate the user
• A valid e-mail address for communication and password resetting
• Resource access information, e.g.,
  • ssh public keys
  • windows authentication credentials
• General metadata, e.g,
  • Real name
  • Affiliation
  • Phone number
  • Address

The API provides an authenticated user (see below) with several interfaces to query and modify their profile information.

In the API each element of profile data is represented as a structure with the following data in it:

• name of the element
• type of the element
  • string
  • integer
  • double
  • binary/opaque
  • lists of any of the above
• value(s) of the element
• a flag set if the element is optional
• a modification type: elements may be read/write, read-only (e.g., username) or write-only (e.g., password)
• a brief description of the field, intended to be presented by a web interface or other third party program

The interfaces to manipulate a profile are

• GetProfileDescription
  • No input required
  • Returns a set of empty elements that this testbed understands and requires, represented as above
• GetUserProfile
  • No input required execpt an authenticated user
  • Returns a populated set of elements containing the current values of the user's profile
• SetUserProfile
  • A list of populated elements that the (authenticated) user wishes to change in the current profile
  • A list of the elements successfully updated, and a list of those that failed with a reason for each

Authenticating as a User

A user represnts themself to the testbed by presenting proof that they hold a public key, for example through an SSL connection. The testbed determines what operations a user can carry out based on an ABAC-encoded policy that grants rights to users and binds keys to users. A user is issued a public key periodically by DETER, but also can request a short lived temporary key at any time by authenticating against a shared password. A temporary key is useful to allow a web application or other hosted tool to act on a user's behalf.