ORCA and RSpec

ORCA supports requests submitted in RSpec v2. Requests in NS2 and RSpec v1 are possible, but require a manual use of the NDL converter and Flukes.

RSpec v2 Requests

ORCA supports a limited set of RSpec expressions. The example below shows a representative sample of what can be said. This RSpec describes a slice with two nodes connected by a single link.

<?xml version="1.0" encoding="UTF-8"?>
<rspec type="request" 
	xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
	          	    http://www.geni.net/resources/rspec/3/request.xsd
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1/request.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:s="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
	xmlns="http://www.geni.net/resources/rspec/3">
<node client_id="geni1" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni1:0">
    <ip address="172.16.22.1" netmask="255.255.255.0" />
 </interface>
</node>
<node client_id="geni2" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni2:0" >
   <ip address="172.16.22.2" netmask="255.255.255.0" />
 </interface>
</node>
<link client_id="center">
  <interface_ref client_id="geni1:0" />
  <interface_ref client_id="geni2:0" />
</link>
</rspec>

NOTE: The example above is provided for informational purposes only and needs to be modified to use a valid disk image.

Request conversion conventions

  • Disk images - in ORCA users are allowed to specify their own images that can be placed on any webserver to be picked up by ORCA (downloaded and installed on user instances). This functionality is supported via ImageProxy. From the user's perspective what is required is to (see ImageProxy documentation for details):
    • Create an image
    • Create an xml file describing the image
    • Take SHA1 hash of the xml file
    • Place the url of the xml file and the SHA1 sum into the RSpec request. Since RSpec does not natively support this, the URL must be put into the 'name' attribute of the image and the SHA1 sum into the 'version' attribute of the image (see above)
    • We maintain a small library of stock images that can be used as a starting point for customizing an image.
  • Node services:
    • RSpec install and execute services: both are supported. Install service can handle .tar, .tar.gz, .tgz, .zip, .deb and .rpm formats (assuming the OS image has the tools to unpack those formats).
      • Both of these services use ORCA's post-boot scripts internally. Notably, the execute service obeys Velocity template substitution rules, used by post-boot scripts. This also means that these services can be debugged as post-boot scripts, by using the command (on the booted instance).
        $ neuca-user-script
        
    • ORCA allows specifying templated post-boot actions in post-boot scripts. You can specify an entire multi-line boot script as part of 'secvices_post_boot_script' element (note the script text must be HTML-escaped):
      <rspec xmlns="http://www.geni.net/resources/rspec/3"
            xmlns:pbs="http://www.geni.net/resources/rspec/ext/postBootScript/1"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.geni.net/resources/rspec/3
      http://www.geni.net/resources/rspec/3/request.xsd
      http://www.geni.net/resources/rspec/ext/postBootScript/1
      http://www.geni.net/resources/rspec/ext/postBootScript/1/request.xsd"
            type="request">
       <node client_id="foo">
         <services>
           <pbs:services_post_boot_script type="velocity">
      #!/bin/sh
      FILENAME=/tmp/somefile
      echo "Hello from post boot script" &gt; $FILENAME
      DATE=`date`
      echo "Executed on $DATE" &gt;&gt; $FILENAME
      TARURL="http://somehostname.domain.net/important_package.tar.gz
      TARFILE=/tmp/mytar.tar.gz
      curl $TARURL &gt; $TARFILE
      tar -zxf $TARFILE -C /some/directory
           </pbs:services_post_boot_script>
         </services>
       </node>
      </rspec>
      
  • Dataplane IP address - ORCA allows the user to specify the IP address of an interface in a slice dataplane (not to be confused with the management address through which the user logs in). This can be done by adding an 'ip' element within an interface definition (see example above)
  • Management IP address - the address from which the user can have ssh access the sliver. This cannot be specified and is reported as 'service' element within the manifest RSpec. Note that the port may not be 22, as some sites lack direct access to the Internet and use NAT. For these sites Gush may not work well as it requires a listening port open on the sliver which in this case will not be NATted.
  • Domain binding - you can bind different parts of your request to different sites. You can use standard ORCA site names (uncvmsite, rencivmsite, acisvmsite, dukevmsite). Note that nodes in a request can be bound to different domains to create an inter-domain topology. The domain can be specified as part of component_manager_id:
    <node component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm"
            client_id="my-vm">
        <sliver_type name="m1.small" />
    </node>
    
    • NOTE: for better consistency with the rest of GENI, the domain names should be prepended with 'exogeni.net:'. It is optional in the requests, however the manifest will return component manager IDs in this format (with site name prepended with 'exogeni.net:'.
      component_manager_id="urn:publicid:IDN+exogeni.net:uncvmsite+authority+am"
      
    • Domain names are:
      • BBN Rack: bbnvmsite
      • RENCI Rack: rcivmsite
      • Duke: dukevmsite
      • UNC: uncvmsite

Nodegroups

Nodegroups - groups of nodes equivalently connected and configured - are support via an additional attribute 'count' in the node definition, using a nodegroup extension like so:

<?xml version="1.0" encoding="UTF-8"?>
<rspec type="request" 
	xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
	          	    http://www.geni.net/resources/rspec/3/request.xsd
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1/request.xsd
                            http://www.geni.net/resources/rspec/ext/nodegroup/1
                            http://www.geni.net/resources/rspec/ext/nodegroup/1/nodegroup.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:s="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
	xmlns:ng="http://www.geni.net/resources/rspec/ext/nodegroup/1"
	xmlns="http://www.geni.net/resources/rspec/3">
<node client_id="geni1" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <ng:nodegroup count="10" />
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni1:0">
    <ip address="172.16.22.1" netmask="255.255.255.0" />
 </interface>
</node>
<node client_id="geni2" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni2:0" >
   <ip address="172.16.22.2" netmask="255.255.255.0" />
 </interface>
</node>
<link client_id="center">
  <interface_ref client_id="geni1:0" />
  <interface_ref client_id="geni2:0" />
</link>
</rspec>

Storage extensions

LUN volumes can be allocated using the storage extension:

<?xml version="1.0" encoding="UTF-8"?>
<rspec type="request" 
	xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
	          	    http://www.geni.net/resources/rspec/3/request.xsd
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1/request.xsd
			    http://www.geni.net/resources/rspec/ext/storage/1
			    http://www.geni.net/resources/rspec/ext/storage/1/storage.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:s="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
	xmlns:st="http://www.geni.net/resources/rspec/ext/storage/1"
	xmlns="http://www.geni.net/resources/rspec/3">
<node client_id="geni1" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni1:0">
    <ip address="172.16.22.1" netmask="255.255.255.0" />
 </interface>
</node>
<node client_id="storage1" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="storage">
   <!-- capacity is in GB -->
   <st:storage resource_type="LUN" do_format="true" fs_param="-F -b 1024" fs_type="ext4" mnt_point="/mnt" capacity="100" />
 </sliver_type>
 <interface client_id="geni2:0" >
   <ip address="172.16.22.2" netmask="255.255.255.0" />
 </interface>
</node>
<link client_id="center">
  <interface_ref client_id="geni1:0" />
  <interface_ref client_id="geni2:0" />
</link>
</rspec>

OpenFlow extension

Currently a single controller per slice can be specified as follows:

<?xml version="1.0" encoding="UTF-8"?>
<rspec type="request" 
	xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
	          	    http://www.geni.net/resources/rspec/3/request.xsd
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1
                            http://www.protogeni.net/resources/rspec/ext/shared-vlan/1/request.xsd
			    http://www.geni.net/resources/rspec/ext/openflow/4
			    http://www.geni.net/resources/rspec/ext/openflow/4/of-resv.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:s="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
	xmlns:of="http://www.geni.net/resources/rspec/ext/openflow/4"
	xmlns="http://www.geni.net/resources/rspec/3">
<of:config>
	<of:controller url="tcp:192.168.1.1:6633" role="primary" />
</of:config>

<node client_id="geni1" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni1:0">
    <ip address="172.16.22.1" netmask="255.255.255.0" />
 </interface>
</node>
<node client_id="geni2" component_manager_id="urn:publicid:IDN+uncvmsite+authority+cm">
 <sliver_type name="m1.small">
   <disk_image
name="http://geni-images.renci.org/images/standard/debian/deb6-neuca-v1.0.7.xml"
version="ba15fa6f56cc00d354e505259b9cb3804e1bcb73" />
 </sliver_type>
 <interface client_id="geni2:0" >
   <ip address="172.16.22.2" netmask="255.255.255.0" />
 </interface>
</node>
<link client_id="center">
  <interface_ref client_id="geni1:0" />
  <interface_ref client_id="geni2:0" />
</link>
</rspec>

Color extensions

In order to support arbitrary annotation of RSpecs by user tools ExoGENI uses 'color' extensions. They allow to attach properties to nodes and links in RSpec requests and also create dependencies between elements of requests marked with a `color' label that denotes the application namespace. The annotations can take the form of property lists, XML text and plain text. There is a complete example shown in this file.

Manifests

ORCA GENI AM compatibility API produces manifests consistent with GENI RSpec v3 schema and the stitching schema.

What is not supported

The following ORCA features are not supported in RSpec requests and/or API.

  • Nodegroups and nodegroup ORCA-driven splitting, automated dataplane address assignment
  • Functional dependencies between nodes
  • Slice modifications