HowTo/ConvertPLAdToRequest

Creating PlanetLab Request RSpecs from Advertisement RSpecs

In this step by step instructions we are going to use GENI v3 RSpecs and also give intuition about how to use ProtoGENI v2 RSpecs. For an overview of RSpecs used in GENI look here.

You can use any tool that talks the GENI AM API to follow these instructions. For the purpose of this page we are using the  Omni command line tool.

1. Download and save the ad RSpec

Use Omni to download and save the advertised RSpec from the aggregate you care about.

  1. In general the command is:
    $ omni.py -a <url or nickname of aggregate> -t GENI 3 -o listresources
    

If the AM you are using supports ProtoGENI v2 RSpecs then the command will look like:

$ omni.py -a <url or nickname of aggregate> -t ProtoGENI 2 -o listresources

The main difference between ProtoGENI v2 RSpecs and GENI v3 is the location of the schemas. If you are using ProtoGENI v2 then make sure that you replace this URL: http://www.geni.net/resources/rspec/3 with this: http://www.protogeni.net/resources/rspec/2 and vice versa.

For example, to get the request RSpec from the MyPLC at the GPO Lab:

$ omni.py -a pl-gpo -t ProtoGENI 2 -o listresources
  1. The output of this command is:
    geni@geni-tutorial:~/Tutorials/Omni/gpousr20$ omni.py -a pl-gpo -t ProtoGENI 2 -o listresources
    INFO:omni:Loading config file omni_config
    INFO:omni:Using control framework pgeni
    INFO:omni:Saving output to a file.
    INFO:omni:Substituting AM nickname pl-gpo with URL http://myplc.gpolab.bbn.com:12346/, URN unspecified_AM_URN
    INFO:omni:Listed resources on 1 out of 1 possible aggregates.
    INFO:omni:Writing to 'rspec-myplc-gpolab-bbn-com-12346-.xml'
    INFO:omni: ------------------------------------------------------------
    INFO:omni: Completed listresources:
    
      Options as run:
    		aggregate: pl-gpo
    		framework: pgeni
    		native: True
    		output: True
    		rspectype: ('ProtoGENI', '2')
    
      Args: listresources
    
      Result Summary: Retrieved resources from 1 aggregates.
    Wrote rspecs from 1 aggregates to 1 files
    Saved listResources RSpec at unspecified_AM_URN to file rspec-myplc-gpolab-bbn-com-12346-.xml. 
    . 
    INFO:omni: ============================================================
    

2. Copy and edit the RSpec file.

  1. Copy the advertisement RSpec file. The new file will become the request RSpec. In general this would be:
    cp <advertisement RSpec filename> <manifest RSpec filename>
    
    The value of <advertisement RSpec filename> appears in the Omni summary. In this case we will generate a request for the node "navis":
    cp rspec-myplc-gpolab-bbn-com-12346-.xml pl-gpo-navis.rspec
    
  2. Edit the request Rspec file:
    emacs pl-gpo-navis.rspec &
    
    or
    vi pl-gpo-navis.rspec
    
  3. Edit the <rspec> tag.
    1. In the <rspec> tag, remove the expires and generated attributes.
    2. In the <rspec> tag, change the type="advertisement" attribute to type="request".
    3. In the <rspec> tag, change 'ad' to 'request' in the schema location. That is, change this:
      xsi:schemaLocation=""http://www.geni.net/resources/rspec/3 "http://www.geni.net/resources/rspec/3/ad.xsd"
      
      To this:
      xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd"
      
    4. The <rspec> tag should now look like this (note that the whitespace has been adjusted for ease of reading):
      <rspec type="request" 
             xmlns=""http://www.geni.net/resources/rspec/3" 
             xmlns:planetlab="http://www.planet-lab.org/resources/sfa/ext/planetlab/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"> 
      
  4. Remove the node tags you do not want to request.
    1. For example to only reserve the node navis.gpolab.bbn.com remove the following text:
          <node component_id="urn:publicid:IDN+plc:gpolab:gpolab+node+bain.gpolab.bbn.com" 
                component_manager_id="urn:publicid:IDN+plc:gpolab+authority+am" 
                component_name="bain.gpolab.bbn.com" 
                exclusive="false">    
          .... 
         </node>  
          <node component_id="urn:publicid:IDN+plc:gpolab:gpolab+node+sardis.gpolab.bbn.com" 
                component_manager_id="urn:publicid:IDN+plc:gpolab+authority+am" 
                component_name="sardis.gpolab.bbn.com" 
                exclusive="false">
          ....     
         </node>  
          <node component_id="urn:publicid:IDN+plc:gpolab:gpolab+node+ganel.gpolab.bbn.com" 
                component_manager_id="urn:publicid:IDN+plc:gpolab+authority+am" 
                component_name="ganel.gpolab.bbn.com" exclusive="false">
          ....     
         </node>  
          <node component_id="urn:publicid:IDN+plc:gpolab:gpolab+node+gardil.gpolab.bbn.com" 
                component_manager_id="urn:publicid:IDN+plc:gpolab+authority+am" 
                component_name="gardil.gpolab.bbn.com" exclusive="false">    
          .... 
          </node> 
      
    2. At this point the entire file should look like this:
      <?xml version="1.0" ?>
      <!-- Resources at AM:
      	URN: unspecified_AM_URN
      	URL: http://myplc.gpolab.bbn.com:12346/
       -->
      <rspec type="request" 
             xmlns=""http://www.geni.net/resources/rspec/3" 
             xmlns:planetlab="http://www.planet-lab.org/resources/sfa/ext/planetlab/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">  
          <node component_id="urn:publicid:IDN+plc:gpolab:gpolab+node+navis.gpolab.bbn.com" component_manager_id="urn:publicid:IDN+plc:gpolab+authority+am" component_name="navis.gpolab.bbn.com" exclusive="false">    
              <hardware_type name="plab-pc"/>    
              <hardware_type name="pc"/>    
              <available now="true"/>    
              <sliver_type name="plab-vnode">      
                  <planetlab:initscript name="gpolab_sirius"/>      
              </sliver_type>    
              <location country="us" latitude="42.3897" longitude="-71.1475"/>    
          </node>  
      </rspec>
      
  5. Edit the <node> tag you are trying to reserve.
    1. Remove all <hardware_type>, <available>, <location>, and <planetlab:initscript"/> tags which exist from the <node> tag you are trying to reserve.
    2. Add the attribute client_id to the <node> tag you are trying to reserve. The value is your choice, so here we will use client_id="navis".
    3. The final request RSpec file should look like this:
      <?xml version="1.0" ?>
      <!-- Resources at AM:
      	URN: unspecified_AM_URN
      	URL: http://myplc.gpolab.bbn.com:12346/
       -->
      <rspec type="request" 
             xmlns="http://www.protogeni.net/resources/rspec/2" 
             xmlns:flack="http://www.protogeni.net/resources/rspec/ext/flack/1" 
             xmlns:planetlab="http://www.planet-lab.org/resources/sfa/ext/planetlab/1" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="http://www.protogeni.net/resources/rspec/2 http://www.protogeni.net/resources/rspec/2/request.xsd">  
          <node component_id="urn:publicid:IDN+plc:gpolab:gpolab+node+navis.gpolab.bbn.com" component_manager_id="urn:publicid:IDN+plc:gpolab+authority+am" component_name="navis.gpolab.bbn.com" exclusive="false" client_id="navis">    
              <sliver_type name="plab-vnode">         
              </sliver_type>    
          </node>  
      </rspec>
      
  6. Save the file.

3. Run rspeclint

 rspeclint is a program that helps you verify the validity of an RSpec document.

 Download rspeclint and invoke it to validate your rspec. If it works, you should see no errors returned by the call.

In general, this is:

rspeclint <request RSpec filename>

For this example do:

rspeclint  pl-gpo-navis.rspec