RSpec Reference Guide

There are three incarnations of resource specifications: advertisements, requests, and manifests. They share many features in common. We will first describe their common tags and then discuss each one in detail.

Basic Structure

RSpecs consist of three basic kinds of things: nodes, interfaces, and links.

Interfaces are defined within nodes and referenced by links. Each interface is associated with one and only one node. Configuration and other information about interfaces is contained at the site of that interface's definition and interface references contain only the id of that interface.

All core rspec tags are within the rspec namespace. The core schema expects verifies only tags in the core rspec namespace and accepts any elements or attributes outside of that namespace as valid.

All timestamps are formatted to be RFC 3339 compliant.

RSpec and extension versions are specified by the namespace URN.

<rspec>

type="advertisement|request|manifest"

This is the type of rspec. This field is used to help disambiguate a resource specification.

generated="timestamp" (optional)

When this document was generated. May be used for determining staleness.

generated_by="text" (optional)

Who/what generated the timestamp. No fixed format. Should not be used for policy decisions.

expires="timestamp" (optional)

The time at which this rspec becomes invalid. May be used for determining staleness when caching.

<link> (list)

A description of a communications channel. Links are communications channels among nodes.

<node> (list)

A description of a node which is either available (ad), requested (request), or provided (manifest). Nodes are processors, routers, networks, or other configurable entities.

<relation> (list)

It is often useful to describe different kinds of relations among nodes. In an advertisement, this is informational. For instance, one node may be hosted inside of another node (NetFPGA cards) or two nodes might share important resources. In a request, it may function as a constraint, for instance specifying that two nodes should be colocated on the same physical node. This tag provides a flexible way to describe any such relationship using the extensions mechanism.

type="text"

This is an identifier used to denote a particular kind of relation. If other information about the relationship besides its type needs to be transmitted, that information can be part of an extension keyed to that particular relation type. The semantic meaning of these relation types is specified by the AMs which implement them.

component_id="urn" (ad)

The component_id of the other node in this advertisement which is related to this node.

client_id="text" (request, manifest)

The client_id of the other node in this request which is related to this node.

<location> (optional)

Information about where this node is located in the physical world.

country="code"

The two-letter ISO 3166 country code which the node is located in. This is required because users may need to conform to applicable law for that country.

longitude="number" latitude="number" (optional)

Longitude and latitude are the coordinates of the node using the WGS 84 standard. If a CM does not wish to disclose this information, these should be omitted.

<services> (optional)

What additional services are provided for this node. Services include tarball installation, startup commands, and shell logins.

<login> (list)

Provides information on whether (and how) a user can log into a shell on the node interactively.

authentication="text"

This field describes the authentication mechanism for logging in via shell. Currently the only mechanism supported is 'ssh-keys' which uses the keys passed in via CreateSliver or RedeemTicket. Other authentication mechanisms can be defined and information about them can be added as part of an extension.

hostname="text" (optional)

The hostname used to contact this node when logging in. Note that this hostname need not be unique to this node. For instance, an AM could have a separate SSH server set up which proxies to serial consoles on the backend.

port="number" (optional)

The port to contact when ssh'ing to this node. If absent, the default is port 22.

<execute> (list)

Describes the execution environment for running automated startup commmands on this node. These commands might notify you when they are up, start a web server for configuration, etc.

shell="text"

The shell used to execute the startup command. Should usually be 'sh' but may be different if the shell is being provided on a non-unix system for instance.

command="text" (request, manifest)

The actual command to execute. This command is often executed as a sudoer so that the command can use 'sudo' to execute as root if need be. Make sure to fully qualify paths where possible here.

<install> (list)

An AM may allow you to specify software to be installed on a node from a particular web location. Any software installation done with this tag happens before scripts are executed via the <execute> tag.

file_type="text"

This should describe the extension of archival formats accepted by an AM or requested by a user. Currently file types are 'tar.gz' or 'tar.bz2'.

url="url" (request, manifest)

The URL which contains the archive to be installed on the node. The archive may be downloaded just once by the AM during slice creation if multiple nodes specify the same URL.

install_path="path" (request, manifest)

The path where the archive will be unpacked.

<interface> (list)

Interfaces bind nodes to links. Interfaces are defined inside of a node and all information associated with that interface should be located here.

<link>