= RSpec Tutorial =

This tutorial explains the basic concepts used in [wiki:RSpec] and how to accomplish certain common tasks.

[[TOC]]

== Key features of the ProtoGENI RSpec ==

  * Identifying resources
    * All nodes and links are identified by URN
  * Nodes
    * Node have types
    * Geographic information can be attached
    * Virtualization technology is included as a field
    * Descriptions of additional optional facilities provided by the component manager (e.g.
      login protocols, installation of software, commands to run) can be supplied
  * Links
    * Links are point-to-point: LANs and other "full connectivity" environments 
      (such at the Internet), a "LAN node" is created, and all members are linked to it.
    * Links have bandwidth, a type, etc.
    * Links endpoints reference Interfaces on Nodes
    * Links have [wiki:LinkTypes] which describe how experimental traffic is to be encapsulated and what layer(s) are supported for that traffic.
  * Interfaces
    * Endpoint of a link
    * Named by node, plus an opaque interface name
    * ''In progress'': Interfaces will be first-class entities, declared as part of the component they belong to
  * Metadata
    * A "valid until" field
    * A "generated" time
  * [wiki:ExternalReferences]
    * A mechanism by which CMs can describe how their components connect with the components in other CMs.
  * Wireless Nodes
    * We need to make special provision for nodes which can communicate wirelessly: [wiki:WirelessRSpec]
  * Extensions (see [wiki:RSpecExtensions])
    * The RSpec must provide an extensions mechanism to accommodate the wide range of stakeholders which will make use of the RSpec.

== How do I use RSpecs? ==

RSpecs interact with nearly every piece of the GENI architecture. This forms a kind of [wiki:RSpecLifeCycle lifecycle] as different kinds of RSpecs are created and modified by different ProtoGENI entities.

The RSpec returned in DiscoverResources is an advertisement which describes the available resources. You must then craft a request specifying which resources you want. There are a number of [wiki:RSpecExample] examples of requests which you can use as a starting point. Finally, when you have created your sliver, you will receive a manifest which gives you additional information about which resources were selected.

== How do I create a request? ==

== How do I install tarballs and setup my node? ==

When constructing your request, you can specify a tarball to install by adding a 'tarfiles' attribute to your node:

{{{
<node ...
      tarfiles="/first/path http://example.com/first/file.tar.gz;/second/path http://example.com/second/file.tar.gz" >
  ...
</node>
}}}

The attribute is a semicolon-delimited list of pairs. Each element in the list contains an install path and a URL pointing to the tarfile separated by a space. The urls will be fetched and the tarfiles will be uncompressed into the specified install directories before any startup commands are executed.

If you want to run a command on startup to set up your node properly, you can add a 'startup_command' attribute to your node:

{{{
<node ...
      startup_command="/path/to/startup/script args"
  ...
</node>
}}}

The startup_command is a shell command which will be executed on startup after any tarballs have been installed.

There is a [wiki:RSpecExamples#tarball complete example] of a request using both of these features.