= How to Share a VLAN (and How to Unshare A VLAN) =

This page describes how to convert an LAN into a shared VLAN without operator intervention. This feature is supported by InstaGENI and ProtoGENI sites for non-trivial VLANs, GENI Stitched VLANs and !OpenFlow VLANs.  The example in this page is for a GENI Rack site and is adapted from an e-mail from Leigh Stoller.

Process to share a VLAN:

 1. Reserve resources which contain a LAN.  
 2. Run `performoperationalaction geni_sharelan` command to set the two options `geni_sharelan_lanname` and `geni_sharelan_token`.  Where `geni_sharelan_lanname` is the `client_id` of the LAN reserved in the previous step and   `geni_sharelan_token` is the name of the new shared VLAN.
 3. Reserve additional resources connected to the LAN shared in the previous step and whose name matches the value of `geni_sharelan_token`.
 4. Resources should now be able to communicate with each other using the shared VLAN.

Process to unshare a LAN:

 1. Run `performoperationalaction geni_unsharelan` to disable the two options `geni_sharelan_lanname` and `geni_sharelan_token` that were originally shared.  
 2. Resources should no longer be able to communicate with each other using the shared VLAN.

== Caveats ==

 1. The LAN being shared must be a real VLAN, not a trivial link between two VMs on the same physical host.  In other words, the minimal case requires two VMs that have a different `component_id`.  GENI stitched VLANs can also be shared as well as VLANs that go through an [http://groups.geni.net/geni/wiki/HowTo/ShareALanOnAHWSwitch OpenFlow hardware switch].
 2. There is no change to idleness or expiration behavior; these resources must be renewed like other resources using the usual mechanisms.
 3. When the shared LAN is unshared, or the slice terminated, all of the other slices that were using that LAN will have the ports yanked out and disabled. However, the resources will remain.  
 4. There is currently no way to determine which slice contains the LAN which is shared. You must keep track of this out-of-band. 
 5. This only works at InstaGENI racks and ProtoGENI Utah.

== Sharing a VLAN ==

This example start with resources in one rack and then add a second slice with resources in the same rack to share the LAN.

 1. Generate a request Rspec with compute resources connected by a non trivial trivial link by requesting resources from different Xen Servers (pc1 & pc2). This example uses uwashington-ig, you should replace the aggregate with one of your choice.  The `client_id` of the LAN that will be shared is `lan0`. Here is an example:
{{{
<rspec type="request" 
xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd"
xmlns:client="http://www.protogeni.net/resources/rspec/ext/client/1" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://www.geni.net/resources/rspec/3">

 <node client_id="VM-1" component_manager_id="urn:publicid:IDN+instageni.washington.edu+authority+cm"
 component_id="urn:publicid:IDN+instageni.washington.edu+node+pc1" exclusive="false" >
    <sliver_type name="emulab-xen"/>
    <interface client_id="VM-1:if0">
      <ip address="192.168.1.1" netmask="255.255.255.0" type="ipv4"/>
    </interface>
 </node>

 <node client_id="VM-2" component_manager_id="urn:publicid:IDN+instageni.washington.edu+authority+cm" 
 component_id="urn:publicid:IDN+instageni.washington.edu+node+pc2" exclusive="false" >
    <sliver_type name="emulab-xen"/>
    <interface client_id="VM-2:if0">
      <ip address="192.168.1.2" netmask="255.255.255.0" type="ipv4"/>
    </interface>
 </node>

 <link client_id="lan0">
   <component_manager name="urn:publicid:IDN+instageni.washington.edu+authority+cm"/>
    <interface_ref client_id="VM-1:if0"/>
    <interface_ref client_id="VM-2:if0"/>
    <property source_id="VM-1:if0" dest_id="VM-2:if0"/>
    <property source_id="VM-2:if0" dest_id="VM-1:if0"/>
    <link_type name="lan"/>
 </link>
</rspec>
}}}

 2. Use `omni` to create a sliver with the resource you selected for your slice.  Once the sliver is ready, run `performoperationalaction` (a.k.a. `poa`) on your slice. The general command is:
  
{{{
omni.py -V 3 -a AGG_NAMEV3 poa SLICE_NAME geni_sharelan --optionsfile lan_options.json
}}}

The contents of `lan_options.json` should be in the form:
{{{
{
 "geni_sharelan_lanname": "LAN_CLIENT_ID",
 "geni_sharelan_token": "STRING_IDENTIFYING_SHARED_LAN"
}
}}}

For example:
{{{
{
 "geni_sharelan_lanname": "lan0",
 "geni_sharelan_token": "janesSpecialLan"
}
}}}

 3. Create the second slice and reserve resources using using an RSpec that: a) defines the shared VLAN schema in RSpec header, b) Uses IP addresses that do not conflict with first slice and c) requests the shared VLAN name matching `STRING_IDENTIFYING_SHARED_LAN` (in our example `janesSpecialLan`). Here is an example:
{{{
<rspec type="request" 
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/shared-vlan/1
           http://www.geni.net/resources/rspec/ext/shared-vlan/1/request.xsd"
xmlns:client="http://www.protogeni.net/resources/rspec/ext/client/1" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:sharedvlan="http://www.geni.net/resources/rspec/ext/shared-vlan/1"
xmlns="http://www.geni.net/resources/rspec/3">

 <node client_id="VM-3" component_manager_id="urn:publicid:IDN+instageni.washington.edu+authority+cm"
 component_id="urn:publicid:IDN+instageni.washington.edu+node+pc3" exclusive="false" >
    <sliver_type name="emulab-xen"/>
    <interface client_id="VM-3:if0">
      <ip address="192.168.1.3" netmask="255.255.255.0" type="ipv4"/>
    </interface>
 </node>

 <link client_id="lan0">
    <interface_ref client_id="VM-3:if0"/>
    <sharedvlan:link_shared_vlan name="janesSpecialLan"/>
 </link>
</rspec>
}}}
 
 4. Once the sliver is ready, login to each node and test your setup by running `ping` between compute nodes in the different slices. This should work.

== Unsharing a VLAN ==

 1.  Use `omni` to run `performoperationalaction` (a.k.a. `poa`) on your slice. The general command is:

{{{ 
omni.py -V 3 -a AGG_NAMEV3 poa SLICE_NAME geni_unsharelan --optionsfile lan_options.json
}}}

The contents of `lan_options.json` are the same for sharing and unsharing the LAN:
{{{
{
 "geni_sharelan_lanname": "LAN_CLIENT_ID",
 "geni_sharelan_token": "STRING_IDENTIFYING_SHARED_LAN"
}
}}}

For example:
{{{
{
 "geni_sharelan_lanname": "lan0",
 "geni_sharelan_token": "janesSpecialLan"
}
}}}

 2. Test your setup by running `ping` between compute nodes in the different slices.  It should ''NOT'' work.