Changes between Version 1 and Version 2 of GEC11NetworkingExperiments/Tutorial


Ignore:
Timestamp:
07/23/11 19:57:25 (11 years ago)
Author:
nriga@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GEC11NetworkingExperiments/Tutorial

    v1 v2  
    1 = Tutorial =
     1[[PageOutline]]
     2
     3= Prework =
     4   1. Download and install [http://www.virtualbox.org/ VirtualBox] on your machine, we have tested versions 4.0.8, 4.0.10, 4.0.12.
     5      * If you run Ubuntu 10.04, it comes with !VirtualBox 3.1.6_OSE, which will not work, please download the latest version. 
     6   2. [https://www.planet-lab.org/GEC11/ Download] the VM image
     7   3. Run !VirtualBox and Import Appliance (File->Import Ampliance), accept the default settings for the VM.
     8   4. Start the VM
     9   5. Change the default password, click on the task bar on the top, on the right on the user 'geni', and choose the Change Password button.
     10   6. Verify that the VM has connectivity. Start Firefox (shortcut on the top bar) and try to load Google. If you can't reach any website, restore VM's Network connection.
     11      * On the far right on the top bar, there is the network icon (two opposite facing arrows).
     12      * Click that icon and choose 'Auto eth0'.
     13      * Try loading the webpage again.
     14
     15= Useful Tips =
     16   * You '''can copy-paste''' between the host and the guest VM.
     17   * In the terminal within the VM, use '''Ctrl-Shift-C to copy''' and '''Ctrl-Shift-V to paste'''.
     18   * vim and emacs editors are installed on the VM, so feel free to use them for editing your files
     19      * If you are using vim, while in command mode to replace a pattern in the file type
     20      {{{
     21      %s/pattern/replace_text/gc
     22      }}}
     23      And press 'y' for the instances of the pattern you want replaced, 'n' otherwise.
     24      * If you are using emacs, press Alt-x and then type
     25      {{{
     26query-replace
     27      }}}
     28      and press ENTER. Enter the pattern to be replaced, press ENTER, enter the text you want to replace it with and press ENTER. Press 'y' for the instances of the pattern you want replaced, 'n' otherwise.
     29   * If you want to have a shared folder between your machine and the VM so that it's easier to transfer files during the tutorial, you have to do this before starting the VM. Follow [http://ozz314.wordpress.com/2008/05/08/virtualbox-shared-folders-between-ubuntu-guest-and-mac-host/ these instructions]   
     30   * If you get an error running OMNI, look at the [http://trac.gpolab.bbn.com/gcf/wiki/OmniTroubleShoot troubleshoot page] for help.
     31 
     32= I. Configure OMNI =
     33The purpose of this first exercise is to configure [http://trac.gpolab.bbn.com/gcf/wiki/Omni Omni] to use your credentials and keys. We strongly recommend that you use the preset account that has been assigned to you, however if you have your own account and you are comfortable with GENI, credentials and ssh keys, you might want to setup Omni to use your own personal credentials, by following [wiki:NikySandbox/Gec11Tutorial#GetYourOwnAccount these instructions].
     34
     35=== 1. Personalize omni_config ===
     36Omni uses as input a configuration file, where you can specify information such as which clearinghouse to use, where is your certificate and keys located etc. Under the ''omni_tutorial'' directory, there is a template configuration file,''omni_config'', which you should modify based on your personal settings.
     37
     38   * '''Open a terminal''' (there is a shortcut on the top bar).
     39   * The rest of the tutorial assumes that you are under the omni_tutorial directory :
     40      {{{
     41cd omni_tutorial
     42      }}}
     43   * '''Remove the passphrase''' from your certificate. For security best practices you should keep a passphrase on your certificate.To avoid typing the passphrase throughout the tutorial, we will temporarily remove the passphrase. Run
     44   {{{
     45   ./clear_cert.sh <username>
     46   }}}
     47   It will prompt you for the passphrase which should be included in the slip that was given to you.
     48   * Verify that you have the necessary credential and key files
     49     {{{
     50     ls ssh |grep <username>
     51     }}}
     52     For alice the output looks like :
     53     {{{
     54geni@geni-vm:~/omni_tutorial$ ls ssh | grep alice
     55alice_cert_ct.pem
     56alice_cert.pem
     57alice_key
     58alice_key.pub
     59     }}}
     60
     61   || alice_cert_ct.pem || Cleartext certificate for Alice, i.e. does not require any passphrase ||
     62   || alice_cert.pem || Encrypted certificate for Alice ||
     63   || alice_key || The private key that Alice would use to login to the nodes ||
     64   || alice_key.pub || The corresponding public key that Alice will ask to be loaded to the nodes ||
     65
     66   * '''Edit the template omni_config'''. Open omni_config and personalize it. For the tutorial you should use the cleartext certificate, but when running your own experiments, for security best practices always use your encrypted certificate.
     67
     68   For ''alice'' using a cleartext certificate the omni_config file looks like :
     69
     70   {{{
     71[omni]
     72default_cf = pgeni
     73users = alice
     74
     75# ---------- Users ----------
     76[alice]
     77urn = urn:publicid:IDN+pgeni.gpolab.bbn.com+user+alice
     78keys = ~/omni_tutorial/ssh/alice_key.pub
     79
     80# ---------- Frameworks ----------
     81[pgeni]
     82type = pg
     83ch = https://www.emulab.net:443/protogeni/xmlrpc/ch
     84sa = https://www.pgeni.gpolab.bbn.com:443/protogeni/xmlrpc/sa
     85
     86# Uncomment the following two lines if you are using
     87# a certificate with a passphrase
     88#cert = ~/omni_tutorial/ssh/<username>_cert.pem
     89#key = ~/omni_tutorial/ssh/<username>_cert.pem
     90
     91# Uncomment the following two lines if you are using
     92# a cleartext cert.
     93cert = ~/omni_tutorial/ssh/alice_cert_ct.pem
     94key = ~/omni_tutorial/ssh/alice_cert_ct.pem
     95   }}}
     96
     97   Note, the pgeni framework definition includes the Utah Emulab clearinghouse, which is the only clearinghouse for ProtoGENI aggregates. For additional configuration details please see the [http://trac.gpolab.bbn.com/gcf/wiki/Omni Omni] page for more details.  The omni_configuration parameters shown define the following:  [[BR]]
     98   || '''Parameter'''   || ''' Use'''  ||
     99   || default_cf||  Default Clearinghouse and credentials used if not specified on the command line.  ||
     100   || users||  users setting used when reserving slices. ||
     101   || urn||  The username URN ||
     102   || keys|| A comma separated list of public ssh key files to be uploaded to the Clearinghouse and to your resources ||
     103   || type||  Clearinghouse/credentials type "pg" indicates ProtoGENI, see the [http://trac.gpolab.bbn.com/gcf/wiki/Omni Omni] page. ||
     104   || ch||  ProtoGENI Clearinghouse URL. ||
     105   || sa|| Slice Authority URL. ||
     106   || cert||  Location of your SSL encrypted certificate (contains both a certificate and a key). ||
     107   || key||  Location of your SSL encrypted key (contains both a certificate and a key). ||
     108   
     109   * Verify that the user URN is correct.
     110     Get the URN from your omni config
     111     {{{
     112     grep urn omni_config
     113     }}}
     114     Verify that it matches the urn in your cert (disregard the leading URI:)
     115     {{{
     116     openssl x509 -noout -text -in ./ssh/<username>_cert_ct.pem | grep 'urn:publicid'
     117     }}}
     118     For Alice the output looks like
     119     {{{
     120geni@geni-vm:~/omni_tutorial$ grep urn omni_config
     121urn = urn:publicid:IDN+pgeni.gpolab.bbn.com+user+alice
     122geni@geni-vm:~/omni_tutorial$ openssl x509 -noout -text -in ./ssh/alice_cert_ct.pem | grep 'urn:publicid'
     123                URI:urn:publicid:IDN+pgeni.gpolab.bbn.com+user+alice, email:alice@pgeni.gpolab.bbn.com
     124     }}}
     125
     126=== 2. Test configuration ===
     127In order to test that our configuration is correct, you can issue a getversion command. For this step we have used !PlanetLab's AM, but you can use any Aggregate Manager(AM).
     128{{{
     129omni.py getversion -a http://www.planet-lab.org:12346
     130}}}
     131
     132Alice decided to use !PlanetLab central :
     133{{{
     134#!xml
     135geni@geni-vm:~/omni_tutorial$ omni.py getversion -a http://www.planet-lab.org:12346
     136INFO:omni:Loading config file omni_config
     137INFO:omni:Using control framework pgeni
     138INFO:omni:AM URN: unspecified_AM_URN (url: http://www.planet-lab.org:12346) has version:
     139INFO:omni:{   'ad_rspec_versions': [   {   'extensions': [   'http://www.protogeni.net/resources/rspec/ext/gre-tunnel/1',
     140                                                   'http://www.protogeni.net/resources/rspec/ext/other-ext/3'],
     141                                 'namespace': 'http://www.protogeni.net/resources/rspec/2',
     142                                 'schema': 'http://www.protogeni.net/resources/rspec/2/ad.xsd',
     143                                 'type': 'ProtoGENI',
     144                                 'version': '2'},
     145                             {   'extensions': [],
     146                                 'namespace': None,
     147                                 'schema': None,
     148                                 'type': 'SFA',
     149                                 'version': '1'}],
     150    'code_tag': '1.0-27',
     151    'code_url': 'git://git.onelab.eu/sfa.git@sfa-1.0-27',
     152    'default_ad_rspec': {   'extensions': [],
     153                            'namespace': None,
     154                            'schema': None,
     155                            'type': 'SFA',
     156                            'version': '1'},
     157    'geni_api': 1,
     158    'hostname': 'www.planet-lab.org',
     159    'hrn': 'plc',
     160    'interface': 'aggregate',
     161    'request_rspec_versions': [   {   'extensions': [   'http://www.protogeni.net/resources/rspec/ext/gre-tunnel/1',
     162                                                        'http://www.protogeni.net/resources/rspec/ext/other-ext/3'],
     163                                      'namespace': 'http://www.protogeni.net/resources/rspec/2',
     164                                      'schema': 'http://www.protogeni.net/resources/rspec/2/request.xsd',
     165                                      'type': 'ProtoGENI',
     166                                      'version': '2'},
     167                                  {   'extensions': [],
     168                                      'namespace': None,
     169                                      'schema': None,
     170                                      'type': 'SFA',
     171                                      'version': '1'}],
     172    'sfa': 1,
     173    'testbed': 'myplc'}
     174INFO:omni: ------------------------------------------------------------
     175INFO:omni: Completed getversion:
     176
     177  Options as run:
     178                aggregate: http://www.planet-lab.org:12346
     179                framework: pgeni
     180                native: True
     181
     182  Args: getversion
     183
     184  Result Summary:
     185Got version for 1 out of 1 aggregates
     186 
     187INFO:omni: ============================================================
     188
     189}}}
     190
     191= II. Make a slice =
     192Before we continue with the rest of the tutorial, we need to create a slice that will contain all our slivers with the different AMs.
     193Since the omni_config specifies using GPO's ProtoGENI as the clearinghouse, your slice will be created in the pgeni.gpolab.bbn.com namespace. 
     194
     195=== 1. Createslice ===
     196For this tutorial we will create a slice named ''<username>slice''; you should always choose a slice name that is meaningful to you. To avoid confusion, avoid creating a slice with the same name as your username (i.e. if your username is ''alice'', don't name your slice ''alice'' too).
     197{{{
     198omni.py createslice <username>slice
     199}}}
     200
     201For Alice this would look like
     202{{{
     203geni@geni-vm:~/omni_tutorial$ omni.py createslice aliceslice
     204INFO:omni:Loading config file omni_config
     205INFO:omni:Using control framework pgeni
     206INFO:omni:Created slice with Name aliceslice, URN urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice, Expiration 2011-07-09 19:41:35
     207INFO:omni: ------------------------------------------------------------
     208INFO:omni: Completed createslice:
     209
     210  Options as run:
     211                framework: pgeni
     212                native: True
     213
     214  Args: createslice aliceslice
     215
     216  Result Summary: Created slice with Name aliceslice, URN urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice, Expiration 2011-07-09 19:41:35
     217 
     218INFO:omni: ============================================================
     219}}}
     220
     221=== 2. Renew Slice ===
     222Note in the above output that our new slice expires soon. Your slivers can not last longer then your slice, and your resources will go away when the reservation expires. For your experiments be sure to renew your slice for the duration of your experiment. For the tutorial you don't need to extend the lifetime, but if you wanted to, this is what it would look like:
     223
     224{{{
     225omni.py renewslice <username>slice 20110727T00:00:00
     226}}}
     227
     228For Alice the output would like:
     229{{{
     230geni@geni-vm:~/omni_tutorial$ omni.py renewslice aliceslice 20110726T23:00:00
     231INFO:omni:Loading config file omni_config
     232INFO:omni:Using control framework pgeni
     233INFO:omni.protogeni:Requesting new slice expiration '2011-07-26T23:00:00'
     234INFO:omni:Slice aliceslice now expires at 2011-07-26 23:00:00 UTC
     235INFO:omni:Slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice expires on 2011-07-26 23:00:00 UTC
     236INFO:omni: ------------------------------------------------------------
     237INFO:omni: Completed renewslice:
     238
     239  Options as run:
     240                framework: pgeni
     241                native: True
     242
     243  Args: renewslice aliceslice 20110726T23:00:00
     244
     245  Result Summary: Slice aliceslice now expires at 2011-07-26 23:00:00 UTC
     246Slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice expires on 2011-07-26 23:00:00 UTC
     247INFO:omni: ============================================================
     248}}}
     249
     250'''Note:''' You can not renew the slice expiration time to an earlier time that its current expiration time. Also there is no deleteslice operation. However, you can delete all the slivers in your slice and let the slice expire.
     251
     252
     253=== 3. List your Slices ===
     254If you want to find out what slices you currently have, you can use an Omni command to {{{listmyslices}}}.
     255{{{
     256omni.py listmyslices <username>
     257}}}
     258
     259For Alice the output would look like :
     260{{{
     261geni@geni-vm:~/omni_tutorial$ omni.py listmyslices alice
     262INFO:omni:Loading config file omni_config
     263INFO:omni:Using control framework pgeni
     264INFO:omni:User 'alice' has slices:
     265        urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice
     266INFO:omni: ------------------------------------------------------------
     267INFO:omni: Completed listmyslices:
     268
     269  Options as run:
     270                framework: pgeni
     271                native: True
     272
     273  Args: listmyslices alice
     274
     275  Result Summary: Found 1 slices for user 'alice'.
     276 
     277INFO:omni: ============================================================
     278geni@geni-vm:~/omni_tutorial$
     279}}}
     280
     281= III. Make a ProtoGENI sliver =
     282The first resource we are going to add to our slice is a ProtoGENI host.
     283
     284=== 1. Createsliver ===
     285Under the omni_tutorial directory, there is a directory called ''rspecs'' that has all the necessary template rspecs for the tutorial. For this tutorial we are going to use ProtoGENI hosts from GPO's ProtoGENI cluster, as well as Wide Area ProtoGENI hosts from Utah's ProtoGENI cluster.
     286   * If your ProtoGENI host is in the '''emulab.net'''(e.g. pg30.emulab.net), namespace then it belongs to Utah's cluster and you should use Utah's AM, and use '''rspecs/pg_utah.rspec'''
     287   * If your ProtoGENI host is in the '''pgeni.gpolab.bbn.com'''(e.g. pc1.pgeni.gpolab.bbn.com), namespace then it belongs to GPO's cluster and you should use GPO's AM, and '''use rspecs/pg_gpo.rspec'''
     288
     289   * Edit the '''appropriate''' rspec, and modify it based on your information.
     290
     291   Alice was assigned host pg46.emulab.net so she should modify pg_utah.rspec:
     292   {{{
     293#!xml
     294<!--
     295This rspec will reserve one wide-area ProtoGENI host
     296
     297AM: http://www.emulab.net/protogeni/xmlrpc/am
     298-->
     299<!--  This file is a template rspec for GEC 11 tutorial
     300      Advnaced topics in Networking Experiments using GENI
     301      Make sure to replace
     302       - <PCNAME>
     303       - <USERNAME>
     304-->
     305
     306<rspec type="request" xsi:schemaLocation="http://www.protogeni.net/resources/rspec/2 http://www.protogeni.net/resources/rspec/2/request.xsd" xmlns:flack="http://www.protogeni.net/resources/rspec/ext/flack/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.protogeni.net/resources/rspec/2">
     307  <node client_id="pg46"
     308        component_manager_id="urn:publicid:IDN+emulab.net+authority+cm"
     309        component_id="urn:publicid:IDN+emulab.net+node+pg46"
     310        component_name="pg46" exclusive="true">
     311    <sliver_type name="raw-pc">
     312      <disk_image name="urn:publicid:IDN+emulab.net+image+emulab-ops//FEDORA10-STD"/>
     313    </sliver_type>
     314    <services>
     315      <execute command="cd /home/alice/config_dir;./install.sh" shell="sh " />
     316      <install install_path="/home/alice" url="http://192.1.249.147:8383/gec11tutorial_fedora.tar.gz" file_type="tar.gz"/>
     317    </services>
     318  </node>
     319</rspec>
     320
     321   }}}
     322
     323   * After you have modified the rspec, you are ready to reserve your host on the '''appropriate''' AM. For easy access and to be able to copy and paste AM URLs that are used in this tutorial, we made a [wiki:NikySandbox/Gec11Tutorial#AMURLTable table].
     324  {{{
     325omni.py createsliver -a <AM_URL> <username>slice rspecs/<rspec_file>
     326}}}
     327
     328The output should look like :
     329{{{
     330#!xml
     331geni@geni-vm:~/omni_tutorial$ omni.py createsliver -a http://www.emulab.net/protogeni/xmlrpc/am aliceslice rspecs/pg_utah.rspec
     332INFO:omni:Loading config file omni_config
     333INFO:omni:Using control framework pgeni
     334INFO:omni:Slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice expires on 2011-07-26 23:00:00 UTC
     335INFO:omni:Creating sliver(s) from rspec file rspecs/pg_utah.rspec for slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice
     336INFO:omni:Asked http://www.emulab.net/protogeni/xmlrpc/am to reserve resources. Result:
     337INFO:omni:<?xml version="1.0" ?>
     338INFO:omni:<!-- Reserved resources for:
     339        Slice: aliceslice
     340        At AM:
     341        URL: http://www.emulab.net/protogeni/xmlrpc/am
     342 -->
     343INFO:omni:<rspec type="manifest" xmlns="http://www.protogeni.net/resources/rspec/2" xmlns:flack="http://www.protogeni.net/resources/rspec/ext/flack/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/manifest.xsd"> 
     344    <node client_id="pg46" component_id="urn:publicid:IDN+emulab.net+node+pg46" component_manager_id="urn:publicid:IDN+emulab.net+authority+cm" component_name="pg46" exclusive="true" sliver_id="urn:publicid:IDN+emulab.net+sliver+44220">   
     345        <sliver_type name="raw">     
     346            <disk_image name="urn:publicid:IDN+emulab.net+image+emulab-ops//FEDORA10-STD"/>     
     347        </sliver_type>   
     348        <services>     
     349            <execute command="cd /home/alice/config_dir;./install.sh" shell="sh "/>     
     350            <install file_type="tar.gz" install_path="/home/alice" url="http://192.1.249.147:8383/gec11tutorial_fedora.tar.gz"/>     
     351          <login authentication="ssh-keys" hostname="pg46.emulab.net" port="22" username="alice"/>    </services>   
     352      <rs:vnode name="pg46" xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1"/>  </node> 
     353</rspec>
     354INFO:omni: ------------------------------------------------------------
     355INFO:omni: Completed createsliver:
     356
     357  Options as run:
     358                aggregate: http://www.emulab.net/protogeni/xmlrpc/am
     359                framework: pgeni
     360                native: True
     361
     362  Args: createsliver aliceslice rspecs/pg_utah.rspec
     363
     364  Result Summary: Slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice expires on 2011-07-26 23:00:00 UTC
     365Reserved resources on http://www.emulab.net/protogeni/xmlrpc/am. 
     366INFO:omni: ============================================================
     367}}}
     368
     369=== 2. Sliverstatus ===
     370
     371We asked for an exclusive ProtoGENI host, which means that the node needs to be loaded with the right OS and booted, before our sliver is ready to use. This will take a while. We can check the status of our sliver, using the ''sliverstatus'' call.
     372
     373{{{
     374omni.py sliverstatus -a <AM_URL> <username>slice
     375}}}
     376
     377The status will probably be 'not ready', you can continue with the next steps of the tutorial, and we will come back to this node later.
     378
     379= IV. Make a MyPLC sliver =
     380The next resource to reserve is a MyPLC host. In the previous step, you have modified an example rspec to request the resources you need. There is a better way to create rspecs by asking the AM what resources are available and then deciding what you need. Running the listresources command against an AM returns an advertisement rspec, that can be used as a base to create the reservation rspec.
     381
     382=== 1. Listresources ===
     383To find out the available resources in an AM do the following:
     384 
     385   * Find out the URL of the MyPLC AM you have been assigned ([wiki:NikySandbox/Gec11Tutorial#AMURLTable AM table])
     386   * Run listresources, the '-o' option will save the advertisement rspec in a file.
     387   {{{
     388   omni.py listresources -a <AM_URL> -o
     389   }}}
     390   If alice has been assigned a MyPLC host at Stanford this would like
     391   {{{
     392   omni.py listresources -a https://myplc.stanford.edu:12346 -o
     393   }}}
     394   Alice's output would like :
     395   {{{
     396eni@geni-vm:~/omni_tutorial$ omni.py listresources -a https://myplc.stanford.edu:12346 -o
     397INFO:omni:Loading config file omni_config
     398INFO:omni:Using control framework pgeni
     399INFO:omni:Saving output to a file.
     400INFO:omni:Listed resources on 1 out of 1 possible aggregates.
     401INFO:omni:Writing to 'rspec-myplc-stanford-edu.xml'
     402INFO:omni: ------------------------------------------------------------
     403INFO:omni: Completed listresources:
     404
     405  Options as run:
     406                aggregate: https://myplc.stanford.edu:12346
     407                framework: pgeni
     408                native: True
     409                output: True
     410
     411  Args: listresources
     412
     413  Result Summary: Retrieved resources from 1 aggregates.
     414Wrote rspecs from 1 aggregates to 1 files.
     415INFO:omni: ============================================================
     416   }}}
     417   There is a line that specifies what is the output file (INFO:omni:Writing to 'rspec-myplc-stanford-edu.xml')
     418
     419=== 2. Modify advertisement rspec ===
     420We need to modify the advertisement rpec to make it a reservation rspec.
     421
     422   * Copy the advertisement to a reservation rspec
     423   {{{
     424   cp rspec-<AM>.xml rspecs/myplc-<PLACE>.rspec
     425   }}}
     426   For Alice :
     427   {{{
     428cp rspec-myplc-stanford-edu.xml rspecs/myplc-stanford.rspec
     429   }}}
     430
     431   * Modify the rspec file you just created, to request your node. In the SFA rspecs, in order to reserve a node you have to add the ''sliver'' tag(<sliver/>) right before the end of the ''node'' section(</node>). You can either choose to leave the rest of the hosts in the rspec, or remove them; only the nodes with the 'sliver' section would be reserved. So for example Alice needs to reserve node of-planet1.stanford.edu, the rspec would look like
     432   {{{
     433#!xml
     434<?xml version="1.0" ?>
     435<!-- Resources at AM:
     436        URN: unspecified_AM_URN
     437        URL: https://myplc.stanford.edu:12346
     438 -->
     439<RSpec type="SFA">
     440    <network name="plc">
     441        <site id="s1">
     442            <name>        MyPLC      </name>
     443            <node id="n1">
     444                <hostname>          of-planet1.stanford.edu        </hostname>
     445                <sliver/>
     446            </node>
     447        </site>
     448    </network>
     449</RSpec>
     450   }}}
     451   
     452=== 3. Reserve the node ===
     453   {{{
     454   omni.py createsliver -a <AM_URL> <username>slice rspecs/<rspec_file>
     455   }}}
     456
     457    For Alice this would look like:
     458   {{{
     459#!xml
     460geni@geni-vm:~/omni_tutorial$ omni.py createsliver -a https://myplc.stanford.edu:12346 aliceslice rspecs/myplc-stanford.rspec
     461INFO:omni:Loading config file omni_config
     462INFO:omni:Using control framework pgeni
     463INFO:omni:Slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice expires on 2011-07-26 23:00:00 UTC
     464INFO:omni:Creating sliver(s) from rspec file rspecs/myplc-stanford.rspec for slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice
     465INFO:omni:Please run the omni sliverstatus call on your slice aliceslice to determine your login name to PL resources.
     466INFO:omni:Asked https://myplc.stanford.edu:12346 to reserve resources. Result:
     467INFO:omni:<?xml version="1.0" ?>
     468INFO:omni:<!-- Reserved resources for:
     469        Slice: aliceslice
     470        At AM:
     471        URL: https://myplc.stanford.edu:12346
     472 -->
     473INFO:omni:<!-- Resources at AM:
     474        URN: unspecified_AM_URN
     475        URL: https://myplc.stanford.edu:12346
     476 --><RSpec type="SFA">   
     477      <network name="plc">       
     478            <site id="s1">           
     479                  <name>                MyPLC            </name>           
     480                  <node id="n1">               
     481                        <hostname>                    of-planet1.stanford.edu                </hostname>               
     482                        <sliver/>       
     483                  </node>           
     484            </site>       
     485      </network>   
     486</RSpec>
     487INFO:omni: ------------------------------------------------------------
     488INFO:omni: Completed createsliver:
     489
     490  Options as run:
     491                aggregate: https://myplc.stanford.edu:12346
     492                framework: pgeni
     493                native: True
     494
     495  Args: createsliver aliceslice rspecs/myplc-stanford.rspec
     496
     497  Result Summary: Slice urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+aliceslice expires on 2011-07-26 23:00:00 UTC
     498Reserved resources on https://myplc.stanford.edu:12346. . Please run the omni sliverstatus call on your slice aliceslice to determine your login name to PL resources.
     499INFO:omni: ============================================================
     500
     501}}}
     502If you wanted to reserve MyPLC hosts in other campuses as well, you would need to repeat this process. If for some reason this reservation fails, we have assigned you a backup node, repeat this process for the backup node.
     503
     504=== 4. Login to the nodes --- Omni Scripting ===
     505
     506After reserving the nodes, we are ready to login. When reserving !PlanetLab resources, using a different clearinghouse, the login name that should be used to access the nodes is ''''not'''' the username. The username is listed as part of the sliverstatus call. For common functionality like this that is expected to be used often, omni gives you the capability of writing scripts and including omni as a library.
     507Under omni_tutorial there is a folder 'example_scripts' that includes example python scripts that use Omni. One script that is available is the ''getMyLogin.py'' script that will return the exact command for logging-in to your nodes.
     508{{{
     509./omni_scripts/getMyLogin.py -a <AM URL> <username>slice
     510}}}
     511
     512The script will return the actual command that you would need to use for logging in.
     513
     514For Alice the script would return :
     515
     516{{{
     517================================================================================
     518Aggregate [https://myplc.stanford.edu:12346] has a PlanetLab sliver.
     519of-planet1.stanford.edu's pl_boot_state is:
     520        boot
     521Login using:
     522        xterm -e ssh -i ssh/alice_key pgenigpolabbbncom_aliceslice@of-planet1.stanford.edu &
     523
     524================================================================================
     525}}}
     526
     527
     528=== 5. Test connectivity  ===
     529To verify that everything is working as expected, you should try to ping another host, using a subnet that has pre-established connectivity. First of all let's see how we can figure out the IP of the host we reserved :
     530
     531   * List all the interfaces in your host. You will see that there many interfaces of the form eth1.XXXX
     532   {{{
     533   /sbin/ifconfig
     534   }}}
     535   Part of the output would look like :
     536   {{{
     537   eth1.1750:42147 Link encap:Ethernet  HWaddr 00:B0:D0:E1:6F:78 
     538          inet addr:10.42.147.90  Bcast:10.42.147.255  Mask:255.255.255.0
     539          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     540
     541   eth1.1750:42148 Link encap:Ethernet  HWaddr 00:B0:D0:E1:6F:78 
     542          inet addr:10.42.148.90  Bcast:10.42.148.255  Mask:255.255.255.0
     543          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     544   }}}
     545
     546   * Figure out the last octet of the IP address of your host. The way these MyPLC hosts are setup, is that they have multiple subinterfaces, each configured to be part of a different IP subnet. Almost all subnets in the hosts are in the form of 10.42.Y.0/24. You will notice that for all these subnets, your host has the same last octet.  In the example above all the subinterfaces of eth1, will have an IP address that will end in '''90''' (10.42.147.'''90''', 10.42.148.'''90''')
     547
     548   * Proconfigured subnet. We have already made the necessary configuration for subnet with Y=131(10.42.131.0/24), so the IP of your host is 10.42.131.<octet>.
     549Alice has reserved node of-planet1.stanford.edu, whose IP ended up being 10.42.131.'''90'''.
     550
     551Ask your neighbor about their MyPLC IP and try pinging it. Alice's neighbor has reserved node 'gardil.gpolab.bbn.com', with IP (10.42.131.52), feel free to use Alice, or her neighbor, if your's is not ready yet (make sure the node you are pinging is not your own node).
     552
     553   {{{
     554[pgenigpolabbbncom_aliceslice@of-planet1 ~]$ ping 10.42.131.52
     555PING 10.42.131.52 (10.42.131.52) 56(84) bytes of data.
     55664 bytes from 10.42.131.52: icmp_seq=1 ttl=64 time=3466 ms
     55764 bytes from 10.42.131.52: icmp_seq=3 ttl=64 time=1479 ms
     55864 bytes from 10.42.131.52: icmp_seq=4 ttl=64 time=510 ms
     559   }}}
     560
     561= V. Run a Layer 2 ping =
     562The mesoscale GENI resources are connected on Layer 2, which enables Layer 2, i.e. non-IP experiments. In this exercise we are going
     563to run a layer 2 ping program, where we are going to send raw Ethernet frames of a custom Ethernet type to a server and receive a reply.
     564Currently MyPLC only supports IP experiments, so we will use our ProtoGENI host which we have reserved in the beginning.
     565   * check that your sliver is ready
     566   {{{
     567   omni.py sliverstatus -a <AM_URL> <username>slice
     568   }}}
     569
     570   * If your sliver is ready, login to the node
     571   {{{
     572   ssh -i /ssh/<username>_key <username>@<host>
     573   }}}
     574   
     575   For Alice, that has reserved nod pg46.emulab.net:
     576   {{{
     577   ssh -i /ssh/alice_key alice@pg46.emulab.net
     578   }}}
     579
     580   * Check to see that the software has been downloaded :
     581   {{{
     582   [alice@protogeni1 ~]$ ls
     583   config_dir  pingPlus
     584   }}}
     585
     586   * Configure the node. When you login to the node, the data interface of the host is not configured.
     587   {{{
     588    [alice@protogeni1 ~]$ /sbin/ifconfig
     589   }}}
     590   This should list only two interface, the loopback and the control interface. Part of the tarball that was downloaded, is a script that will configure the node, and compile the Layer 2 ping software. Run
     591   {{{
     592    ./config_dir/configure.sh
     593   }}}
     594   The output for Alice would look like
     595   {{{
     596[alice@protogeni1 ~]$ ./config_dir/configure.sh
     597DEVICE=eth1.1750
     598 USERCTL=no
     599 VLAN=yes
     600 IPADDR=10.42.131.146
     601 NETMASK=255.255.255.0
     602 BOOTPROTO=static
     603 ONBOOT=yes
     604
     605Added VLAN with VID == 1750 to IF -:eth1:-
     606gcc    -c -o packetFunctions.o packetFunctions.c
     607gcc    -c -o pingPlusListener.o pingPlusListener.c
     608gcc  packetFunctions.o pingPlusListener.o  -o pingPlusListener
     609gcc    -c -o pingPlus.o pingPlus.c
     610gcc  packetFunctions.o pingPlus.o -o pingPlus
     611   }}}
     612   Verify that the data interface is up :
     613   {{{
     614   [alice@protogeni1 ~]$ /sbin/ifconfig
     615   }}}
     616   and note the name of the data interface, the data interface is the one that has an IP address in the 10.42.131.0/24 subnet:
     617   {{{
     618   eth1.1750 Link encap:Ethernet  HWaddr 00:1F:29:32:92:4D 
     619          inet addr:10.42.131.146  Bcast:10.42.131.255  Mask:255.255.255.0
     620          inet6 addr: fe80::21f:29ff:fe32:924d/64 Scope:Link
     621          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     622          RX packets:118 errors:0 dropped:0 overruns:0 frame:0
     623          TX packets:115 errors:0 dropped:0 overruns:0 carrier:0
     624          collisions:0 txqueuelen:0
     625          RX bytes:5428 (5.3 KiB)  TX bytes:3482 (3.4 KiB)
     626
     627   }}}
     628   In this case the name is 'eth1.1750'.
     629
     630   * Run the Layer 2 Ping
     631   We have pre-configured the network to forward along Layer2 packets of Ethernet type '10131', so let's try pinging with that.
     632   The software that is going to send Layer 2 pings, is called pingPlus. Change to the pingPlus directory :
     633   {{{
     634   cd pingPlus
     635   }}}
     636   There is a server running at a host with mac address '00:15:17:d4:64:c2'. Run the client :
     637   {{{
     638   sudo ./pingPlus 00:15:17:d4:64:c2 <interface_name> 10131
     639   }}}
     640   For Alice the output would be :
     641   {{{
     642[alice@protogeni1 ~/pingPlus]$ sudo ./pingPlus 00:15:17:d4:64:c2 eth1.1750 10131
     643RQ:'5019+6242' to 0:15:17:d4:64:c2.
     644RL:5019+6242=11261 from 0:15:17:d4:64:c2.
     645   }}}
     646   Send a stream of packets, by specifying the number of packets as the last parameter :
     647   {{{
     648   sudo ./pingPlus 00:15:17:d4:64:c2 <interface_name> 10131 10
     649   }}}
     650   '''Note:'''If the program is stuck waiting for a reply for more than 1 minute, press '''Ctrl-C''' to exit.
     651
     652Congratulations you ran a Layer two experiment across the country!
     653
     654= VI. Make an OpenFlow sliver =
     655
     656In the previous step, we have used a pre-configured setup to run our test. In the mesoscale !OpenFlow GENI resources, the data interface of your hosts is connected to an OpenFlow switch, which by default does not forward any traffic, unless there is an OpenFlow controller running that handles predefined traffic patterns.
     657
     658=== 1. !OpenFlow controller ===
     659In a typical !OpenFlow experiment, the first step is to figure out where you are going to run your controller. The !OpenFlow controller should be able to accept connections from switches. To make this tutorial simpler we are running multiple !OpenFlow controllers centrally, and you can point your traffic to the corresponding controller. The controllers we are running are simple switch controllers, i.e. they make the OpenFlow switches behave like typical layer 2 switches.
     660
     661In the previous example we have pointed all the traffic for subnet 10.42.131.0/24 to a switch !OpenFlow controller, that's why you were able to ping between your hosts, using that subnet.
     662
     663=== 2. !OpenFlow sliver ===
     664Until you have reserved an !OpneFlow sliver, traffic would not be forwarded between your hosts on your assigned subnet.
     665   * From your MyPLC host, ping using your assigned subnet.
     666    {{{
     667    ping 10.42.<subnet-oct>.<host_octet>
     668    }}}
     669    For Alice, that has been assigned subnet 122, this looks like
     670    {{{
     671PING 10.42.122.52 (10.42.122.52) 56(84) bytes of data.
     672From 10.42.122.90 icmp_seq=2 Destination Host Unreachable
     673From 10.42.122.90 icmp_seq=3 Destination Host Unreachable
     674    }}}
     675   * Personalize your rspec. There is a sample !OpenFlow rspec, under the rspecs folder ('''rspecs/of.rspec'''), that you would need to modify in order to reserve the flowspace that has been assigned to you. In the beginning of the file there is a list of tags you would need to replace. More specifically
     676      * <PORT> : This is the port that your controller is listening on; for Alice this is 10122. The host that is running the controller is gardil.gpolab.bbn.com.
     677      * <SUBNET-OCT> : This is the subnet octet that has been assigned to you; for Alice this is 122 (e.g. subnet 10.42.122.0/24)
     678      * <ETH_TYPE> : This is the custom ethernet type that has been assigned to you for the next exercise; for Alice this is 10122
     679
     680   * Create the OpenFlow sliver. The flowspace for the tutorial is managed by an AM running at GPO :
     681   {{{
     682   omni.py createsliver <username>slice ./rspecs/of.rspec -a https://expedient-tutorial.gpolab.bbn.com:1443/openflow/gapi/
     683   }}}
     684
     685   * Request for traffic to be opted-in. The !OpenFlow Aggregate Administrator has to allow traffic from various nodes to be routed by your !OpenFlow controller. Please let us know that you have created your sliver, so that we can opt-in your traffic.
     686   
     687=== 3. Layer 3 ping using your controller ===
     688Once your slice has been opted in, you can now try pinging again from your MyPLC host. For Alice this would look like :
     689{{{
     690[pgenigpolabbbncom_aliceslice@pl01 ~]$ ping 10.42.122.90
     691PING 10.42.122.90 (10.42.122.90) 56(84) bytes of data.
     69264 bytes from 10.42.122.90: icmp_seq=1 ttl=64 time=3978 ms
     69364 bytes from 10.42.122.90: icmp_seq=2 ttl=64 time=2979 ms
     694}}}
     695
     696=== 4. Layer 2 ping using your controller ===
     697Now that your slice has been opted-in, you can run a layer two ping using your assigned ETH_TYPE, that you specified in your !OpenFlow rspec.
     698From your ProtoGENI host :
     699{{{
     700   sudo ./pingPlus 00:15:17:d4:64:c2 <interface_name> <eth_type> 10
     701}}}
     702   
     703Part of Alice's output would be :
     704   {{{
     705[alice@protogeni1 ~/pingPlus]$ sudo ./pingPlus 00:15:17:d4:64:c2 eth1.1750 10122 10
     706RQ:'5019+6242' to 0:15:17:d4:64:c2.
     707RL:5019+6242=11261 from 0:15:17:d4:64:c2.
     708   }}}
     709
     710= VII. Cleanup resources =
     711Although all your reservations, have expiration times, its always good practice to release the resources, after your experiment is over to make them available to other experimenters.
     712
     713=== 1. Deletesliver ===
     714For each createsliver that you have run, you will need to run deletesliver to release the resources
     715{{{
     716omni.py deletesliver -a <AM URL> <username>slice
     717}}}
     718For Alice this would look like
     719{{{
     720# Delete ProtoGENI sliver
     721omni.py deletesliver -a http://www.emulab.net/protogeni/xmlrpc/am aliceslice
     722
     723# Delete MyPLC slivers
     724omni.py deletesliver -a https://myplc.stanford.edu:12346 aliceslice
     725
     726#Delete OpenFlow slivers
     727 omni.py deletesliver -a https://expedient-tutorial.gpolab.bbn.com:1443/openflow/gapi/ aliceslice
     728}}}
     729
     730You can not delete your slice. Although this will be cleaned up when it expires, it should be an empty container and thus does not hold up any resources.
     731
     732Congratulations, you have finished the tutorial! Now you are ready to design and run your own experiments. Don't hesitate to [mailto:help@geni.net email us] with any questions you might have.
     733
     734= VII. Get Your Own Account =
     735The accounts, that you used in the above steps, will be deactivated after the tutorial. If you do not already have an account at GPO's ProtoGENI cluster, you should get your own account so that you can further experiment with GENI.
     736
     737=== 1a. Get a temporary account ===
     738To get a temporary account that will be deactivated on August 12th 2011, apply for an account at this page https://www.pgeni.gpolab.bbn.com/joinproject.php3. For Project name use : Gec11Gpo.
     739
     740=== 1b. Get a permanent account ===
     741If you would like to run your own experiments in this infrastructure, please contact us at [mailto:help@geni.net] to get a permanent account.
     742
     743=== 2. Configure Omni with your personal info ===
     744Now that you have your own account, you should configure Omni to use your own personal info, instead of the pre-made accounts.
     745==== 1. Generate and Download your ProtoGENI certificate ====
     746      a. Start Firefox within the VM and [https://www.pgeni.gpolab.bbn.com/login.php3] log in to your account.
     747      b. Select ''Generate SSL Cert'' and follow instructions.
     748      c. Select ''Download your SSL Cert'' (it's on the left of the page), and click on the 'Download it in PEM format' link.
     749      d. Copy the contents of the page (Ctrl-A, Ctrl-C)
     750      e. Open a terminal (there is a shortcut on the top bar) under the omni_tutorial directory there should be an ssh directory
     751      {{{
     752cd omni_tutorial/ssh
     753      }}}
     754      f. Open a file called <username>_cert.pem, paste your cert(Ctrl-Shift-V) and save.
     755      {{{
     756pico <username>_cert.pem>
     757Ctrl-Shift-V
     758Ctrl-X
     759      }}}
     760      g. Remove the passphrase from your certificate. For security best practices you should keep a passphrase on your certificate. If you want to avoid typing your passphrase throughout the tutorial, you might want to temporarily remove your passphrase
     761      {{{
     762openssl rsa -in ./<username>_cert.pem -out ./<username>_cert_ct.pem
     763openssl x509 -in ./<username>_cert.pem >> ./<username>_cert_ct.pem
     764chmod 400 ./<username>_cert_ct.pem
     765      }}}
     766       If you want a way to type your passphrase only once per session, look [http://trac.gpolab.bbn.com/gcf/wiki/OmniTroubleShoot#Q.WhydoesOmnipromptformyPEMpassphrasesomanytimesCantOmnipromptonlyonce here].
     767
     768==== 2. Generate a pair of private/public keys. ====
     769In order to be able to login to the resources you will reserve will need a pair of keys. You can use any set of existing keys you might have, or you can generate a new pair. For security best practices you should  have a passphrase on your keys.
     770{{{
     771ssh-keygen -f <username>_key
     772}}}
     773
     774Now you can go back to [wiki:NikySandbox/Gec11Tutorial#I.ConfigureOMNI (I)] and follow the steps using your own certificate and key.
     775
     776
     777= AM URL Table =
     778|| AM || URL ||
     779|| TUTORIAL AM ||||
     780|| Clemson's MyPLC || http://myplc.clemson.edu:12346 ||
     781|| GPO's ProtoGENI || http://www.pgeni.gpolab.bbn.com/protogeni/xmlrpc/am ||
     782|| GPO's MyPLC || http://myplc.gpolab.bbn.com:12346 ||
     783|| GPO's Tutorial OF ||https://expedient-tutorial.gpolab.bbn.com:1443/openflow/gapi/ ||
     784|| Rutgers MyPLC || https://plc.orbit-lab.org:12346/ ||
     785|| Stanford's MyPLC || https://myplc.stanford.edu:12346 ||
     786|| Utah's ProtoGENI || http://www.emulab.net/protogeni/xmlrpc/am ||
     787|| Washington's MyPLC || https://of.cs.washington.edu:12346/ ||
     788|| Wisconsin's MyPLC || https://wings-openflow-1.wail.wisc.edu:12346/ ||
     789|| OTHER || ||
     790|| !PlanetLab ||http://www.planet-lab.org:12346 ||
     791|| Kentucky's ProtoGENI || https://www.uky.emulab.net/protogeni/xmlrpc/am ||
     792