Changes between Initial Version and Version 1 of GEC15Agenda/IntroToOmni/Instructions


Ignore:
Timestamp:
10/14/12 13:33:05 (11 years ago)
Author:
nriga@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GEC15Agenda/IntroToOmni/Instructions

    v1 v1  
     1[[PageOutline]]
     2
     3= 1. Using Omni =
     4== 1a. Configure Omni ==
     5In order to configure Flack, you needed to login to your account in Emulab and instruct Flack to load your user information (certificate and public keys).
     6For Omni we need to do something similar. Omni uses a configuration file, and there is a script that will automatically generate the file with
     7some default options and place it in the default place of ~/.gcf/.
     8
     9Go back to your browser, and go to the ProtoGENI WebUI tab. On the left of your screen, there should be a link "Download your cert".
     10
     11[[Image(download_cert.png)]]
     12
     13Click on that and select the option about downloading as a pem file.
     14Press '''`Ctrl-s`''' to save this page. Save it under ~/.ssl/geni_cert.pem. You will need to type the path, instead of navigating to the folder.
     15
     16[[Image(save_cert.png, 40%)]]
     17
     18Open a terminal window and type :
     19{{{
     20omni-configure.py
     21}}}
     22This should configure your Omni, with your downloaded certificate and create an ssh key pair for logging in to nodes.
     23When prompted for a passphrase, type the same passphrase you used in Flack. You might be asked for a passphrase
     24multiple times.
     25
     26The output should look like:
     27{{{
     28geni@geni-vm:~$ omni-configure.py
     29{'framework': 'pg', 'configfile': '~/.gcf/omni_config', 'plkey': '~/.ssh/geni_pl_key', 'cert': '~/.ssl/geni_cert', 'verbose': False}
     30INFO:omniconfig:Using configfile: /home/geni/.gcf/omni_config
     31INFO:omniconfig:Using certfile /home/geni/.ssl/geni_cert.pem
     32INFO:omniconfig:
     33
     34        CREATING SSH KEYPAIR
     35INFO:omniconfig:Private key stored at: /home/geni/.ssh/geni_key
     36Enter passphrase:
     37INFO:omniconfig:Public key stored at: /home/geni/.ssh/geni_key.pub
     38INFO:omniconfig:Added to /home/geni/.ssh/config this line:
     39        'IdentityFile /home/geni/.ssh/geni_key
     40'
     41INFO:omniconfig:Wrote omni configuration file at: /home/geni/.gcf/omni_config
     42}}}
     43
     44=== OPTIONAL ===
     45Open the file `~/.gcf/omni_config` using either vim or emacs. Close to the top of the file you will see two parameters called `default_cf` and `users`. Your username should be at least listed in the user section. Look for the sections in the file that are named `[pg]` and  `[<username>]`.
     46
     47In the `[<username>]` section, the information need for logging-in to reserved compute resources are provided. It includes your unique user URN and a public key that would be uploaded to the hosts that you reserve.
     48
     49In the `[pg]` section you configure Omni to use your personal information. The cert and the key attribute point to files that we have manually downloaded from pgeni.gpolab.bbn.com. This is equivalent to the Download action of Flack.
     50
     51Another interesting section to look at is the `[aggregate-nicknames]` sections. Flack already knows the URL for all the AMs and present you a list of AMs to choose from using a short, descriptive name. In Omni a user is required to pass the URL for each call to the GENI AM API. In this section the user gets a chance to provide short descriptive names to the URLs that are easier to memorize and use.
     52
     53== 1b. Clear the passphrase from your cert ==
     54When you first logged in to Flack, you had to type your passphrase (password). Flack cashes this information and re-uses it for the duration of the session. Omni will ask you for the phrase multiple times per command. To save time during the tutorial, we are going to remove the passphrase from your cert and your ssh key. There is a script to clear the passphrases. Run :
     55{{{
     56clear-passphrases.py
     57}}}
     58
     59Use the same passphrase(password) as in Flack, you might be prompted for a passphrase multiple times make sure you always use the same passphrase.
     60
     61The output should look like
     62{{{
     63geni@geni-vm:~$ clear-passphrases.py
     64Do you want to remove the passphrase from your cert (/home/geni/.ssl/geni_cert.pem) [Y,n]?y
     65INFO:clearcert:
     66        THIS SCRIPT WILL REPLACE /home/geni/.ssl/geni_cert.pem WITH AN UNENCREPTED CERT. A BACKUP OF THE ORIGINAL CERT WILL BE CREATED
     67
     68INFO:clearcert:The encoded certificate file is backed up at /home/geni/.ssl/geni_cert_enc.pem
     69INFO:clearcert:Removing passphrase from cert...
     70Enter pass phrase for /home/geni/.ssl/geni_cert.pem:
     71writing RSA key
     72INFO:clearcert:Change permissions of /home/geni/.ssl/geni_cert.pem to 0600
     73Do you want to remove the passphrase from you ssh-key (/home/geni/.ssh/geni_key, key used to login to compute resources) [Y,n]?y
     74INFO:clearcert:
     75        THIS SCRIPT WILL REMOVE THE PASSPHRASE FROM YOUR SSH KEY. NO COPY OF THE ORIGINAL PRIVATE KEY WILL BE KEPT
     76Enter PEM pass phrase:
     77Enter passphrase:
     78geni@geni-vm:~$
     79}}}
     80
     81Verify that you have the necessary credential and key files
     82     {{{
     83     ls ~/.ssh ~/.ssl
     84     }}}
     85     The output looks like :
     86     {{{
     87geni@geni-vm:~$ ls ~/.ssh ~/.ssl
     88/home/geni/.ssh:
     89config  geni_key  geni_key.pub
     90
     91/home/geni/.ssl:
     92geni_cert_enc.pem  geni_cert.pem
     93     }}}
     94
     95   || geni_cert.pem || Cleartext certificate, i.e. does not require any passphrase ||
     96   || geni_cert_enc.pem || Encrypted certificate  ||
     97   || geni_key || The private key that you will use to login to the nodes ||
     98   || geni_key.pub || The corresponding public key that will be uploaded to the nodes ||
     99
     100== 1c. Test Omni setup ==
     101In order to test that our configuration is correct, you can issue a getversion
     102command. For this step we have used !PlanetLab's AM, but you can use any
     103Aggregate Manager(AM).
     104{{{
     105omni.py getversion -a http://www.planet-lab.org:12346
     106}}}
     107
     108Or equivalently using the !PlanetLab nickname:
     109{{{
     110omni.py getversion -a plc
     111}}}
     112
     113For the rest of the tutorial we are going to use aggregate nicknames.
     114== 1d. Omni Commands ==
     115
     116=== Listresources in Omni ===
     117Flack goes behind the scenes and call listresources for the AMs that you chose, and draws the resources in a map. In Omni in order to see what is available in each AM you will have to manually invoke listresources. Invoke listresources on utah's ProtoGENI cluster
     118{{{
     119 omni.py listresources -a pg-utah -o
     120}}}
     121
     122The `-o` option will save the output to a file. The filename is chosen by Omni and printed as part of the output. The output will look like :
     123{{{
     124geni@geni-vm:~$ omni.py listresources -a pg-utah -o
     125INFO:omni:Loading config file /home/geni/.gcf/omni_config
     126INFO:omni:Using control framework pg
     127INFO:omni:Saving output to a file.
     128INFO:omni:Substituting AM nickname pg-utah with URL https://www.emulab.net/protogeni/xmlrpc/am, URN unspecified_AM_URN
     129INFO:omni:Listed resources on 1 out of 1 possible aggregates.
     130INFO:omni:Writing to 'rspec-www-emulab-net-protogeni.xml'
     131INFO:omni: ------------------------------------------------------------
     132INFO:omni: Completed listresources:
     133
     134  Options as run:
     135                aggregate: pg-utah
     136                framework: pg
     137                native: True
     138                output: True
     139
     140  Args: listresources
     141
     142  Result Summary: Retrieved resources from 1 aggregates.
     143Wrote rspecs from 1 aggregates to 1 files
     144Saved listresources RSpec at 'unspecified_AM_URN' to file rspec-www-emulab-net-protogeni.xml; .
     145INFO:omni: ============================================================
     146}}}
     147
     148Open the file that Omni saved and just take a look to see how an advertisement RSpec looks like.
     149
     150=== Listmyslices in Omni ===
     151Both Flack and Omni can see all the slices that are created by a user. In Flack there is a list of slices under the user on the left side of the window.
     152In order to see your active slices with Omni, you will have to use the `listmyslices` command.
     153{{{
     154omni.py listmyslices <username>
     155}}}
     156
     157You should see the slice that you created through Flack.
     158
     159== 1e. Logging Into the nodes -- Omni Scripting ==
     160
     161After reserving the nodes, you are ready to login. The login name and port are listed as part of the sliverstatus call, so you can figure out where to login. For common functionality like this that is expected to be used often,
     162omni gives you the capability of writing scripts and including omni as a library.
     163Omni comes with a set of examples (under gcf/examples). One script that is available is the ''readyToLogin.py'' script that will return the exact command for logging-in to the nodes in your sliver.
     164{{{
     165readyToLogin.py -a pg-utah <slicename>
     166}}}
     167
     168The script will return the actual command that you would need to use for logging in.
     169
     170= 2. Topology used for the tutorial =
     171In the first part of the tutorial, each of you created a topology that looks like:
     172
     173[[Image(full_topo_sigmetrics.png, 30%)]]
     174
     175If you notice under node `R2` there is a hidden link : [[Image(node_link.png)]]
     176
     177Try and drug the link behind the node. This is a link on a shared VLAN that connects all of your nodes `R2` with a node that is in Washington DC. The connection between your hosts in Utah and the node in Washington is at Layer 2, i.e. you can send non-IP traffic between your hosts. The actual topology looks more like this:
     178
     179[[Image(actual_topo.png)]]
     180
     181= 3. Sending IP traffic =
     182For the rest of the tutorial we are going to use the whole topology that has been setup. We will start testing our setup by sending IP traffic between our hosts.
     183
     184== 3a. Login to host `R2` ==
     185First login to the R2 host. To do that go to the Flack page and see what is the name of the machine
     186
     187[[Image(hostname.png, 20%)]]
     188
     189In the terminal copy and paste the line from the readyToLogin.py output that corresponds to this machine.
     190
     191[[Image(readytologin_output.png, 40%)]]
     192
     193== 3b. Ping `source` ==
     194After you login to the R2, try to ping source. Run :
     195{{{
     196ping source -c 5
     197}}}
     198
     199Note that you can use the name that is assigned to the host to directly ping the host.
     200
     201An example output should look like :
     202{{{
     203[[inki@r2 ~]$ ping source -c 5
     204PING 10.10.2.1 (10.10.2.1) 56(84) bytes of data.
     20564 bytes from 10.10.2.1: icmp_seq=1 ttl=64 time=1.95 ms
     20664 bytes from 10.10.2.1: icmp_seq=2 ttl=64 time=2.27 ms
     20764 bytes from 10.10.2.1: icmp_seq=3 ttl=64 time=2.04 ms
     20864 bytes from 10.10.2.1: icmp_seq=4 ttl=64 time=1.95 ms
     20964 bytes from 10.10.2.1: icmp_seq=5 ttl=64 time=1.72 ms
     210
     211--- 10.10.2.1 ping statistics ---
     2125 packets transmitted, 5 received, 0% packet loss, time 4005ms
     213rtt min/avg/max/mdev = 1.728/1.992/2.278/0.179 ms
     214}}}
     215
     216From R2 you should also be able to ping PC-WashDC. The IP of  PC-WashDC is '''"192.68.44.26"'''.
     217{{{
     218[uncusr20@r2 ~]$ ping 192.168.44.26 -c 5
     219PING 192.168.44.26 (192.168.44.26) 56(84) bytes of data.
     22064 bytes from 192.168.44.26: icmp_req=1 ttl=64 time=52.7 ms
     22164 bytes from 192.168.44.26: icmp_req=2 ttl=64 time=52.7 ms
     22264 bytes from 192.168.44.26: icmp_req=3 ttl=64 time=52.7 ms
     22364 bytes from 192.168.44.26: icmp_req=4 ttl=64 time=52.7 ms
     22464 bytes from 192.168.44.26: icmp_req=5 ttl=64 time=52.7 ms
     225
     226--- 192.168.44.26 ping statistics ---
     2275 packets transmitted, 5 received, 0% packet loss, time 4007ms
     228rtt min/avg/max/mdev = 52.745/52.754/52.764/0.251 ms
     229
     230}}}
     231
     232Now let's try and ping the PC-WashDC from source. Login to source the same way you logged in to `R2` and run:
     233{{{
     234ping 192.168.44.26 -c 5 -w 5
     235}}}
     236
     237The ping should work. Run a traceroute to see how your packets are routed:
     238{{{
     239traceroute 192.168.44.26
     240}}}
     241
     242You see that your packets are routed through R2. This is because IP forwarding
     243is enabled at R2. Go back to the terminal of R2 and run :
     244{{{
     245[inki@r2 ~]$ cat /proc/sys/net/ipv4/ip_forward                               
     2461
     247}}}
     248
     249Disable IP forwarding:
     250{{{
     251echo "0" | sudo tee /proc/sys/net/ipv4/ip_forward
     252}}}
     253
     254Now try to ping again from source. The ping should time out.
     255{{{
     256[inki@source ~]$ ping 192.168.44.26 -c 5 -w 5
     257}}}
     258
     259= 4. Sending Layer 2 traffic =
     260GENI provides the capability of creating diverse, layer two topologies. The topology you have created includes connection at Layer 2.
     261
     262In this exercise we are going to send Layer 2 traffic between the reserved hosts.
     263
     264== 4a. Bring Down IP at `R2` ==
     265First of all lets bring down the IP configuration from our hosts. At the terminal  of `R2` first run the `ifconfig` command to figure out which are the dataplane interfaces. Run :
     266{{{
     267/sbin/ifconfig
     268}}}
     269
     270The output should look like :
     271{{{
     272[uncusr20@r2 ~]$ /sbin/ifconfig
     273eth999    Link encap:Ethernet  HWaddr 00:00:AC:13:6D:01 
     274          inet addr:172.19.109.1  Bcast:172.31.255.255  Mask:255.240.0.0
     275          inet6 addr: fe80::200:acff:fe13:6d01/64 Scope:Link
     276          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     277          RX packets:32835 errors:0 dropped:0 overruns:0 frame:0
     278          TX packets:14403 errors:0 dropped:0 overruns:0 carrier:0
     279          collisions:0 txqueuelen:0
     280          RX bytes:47254606 (45.0 MiB)  TX bytes:743825 (726.3 KiB)
     281
     282gre3      Link encap:Ethernet  HWaddr 00:18:51:B5:7A:64 
     283          inet addr:10.20.3.1  Bcast:10.20.3.255  Mask:255.255.255.0
     284          inet6 addr: fe80::218:51ff:feb5:7a64/64 Scope:Link
     285          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     286          RX packets:8 errors:0 dropped:0 overruns:0 frame:0
     287          TX packets:409 errors:0 dropped:0 overruns:0 carrier:0
     288          collisions:0 txqueuelen:0
     289          RX bytes:296 (296.0 b)  TX bytes:26384 (25.7 KiB)
     290
     291lo        Link encap:Local Loopback 
     292          inet addr:127.0.0.1  Mask:255.0.0.0
     293          inet6 addr: ::1/128 Scope:Host
     294          UP LOOPBACK RUNNING  MTU:16436  Metric:1
     295          RX packets:3 errors:0 dropped:0 overruns:0 frame:0
     296          TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
     297          collisions:0 txqueuelen:0
     298          RX bytes:336 (336.0 b)  TX bytes:336 (336.0 b)
     299
     300mv1.1     Link encap:Ethernet  HWaddr 02:00:9B:48:3E:20 
     301          inet addr:10.20.1.2  Bcast:10.20.1.255  Mask:255.255.255.0
     302          inet6 addr: fe80::9bff:fe48:3e20/64 Scope:Link
     303          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     304          RX packets:1022 errors:0 dropped:0 overruns:0 frame:0
     305          TX packets:223 errors:0 dropped:0 overruns:0 carrier:0
     306          collisions:0 txqueuelen:0
     307          RX bytes:80442 (78.5 KiB)  TX bytes:22537 (22.0 KiB)
     308
     309mv1.2     Link encap:Ethernet  HWaddr 02:00:AE:44:FF:E4 
     310          inet addr:192.168.44.70  Bcast:192.168.255.255  Mask:255.255.0.0
     311          inet6 addr: fe80::aeff:fe44:ffe4/64 Scope:Link
     312          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     313          RX packets:10 errors:0 dropped:0 overruns:0 frame:0
     314          TX packets:19 errors:0 dropped:0 overruns:0 carrier:0
     315          collisions:0 txqueuelen:0
     316          RX bytes:866 (866.0 b)  TX bytes:1406 (1.3 KiB)
     317}}}
     318
     319The two interfaces that are connected to `source` and `PC-WashDC` are `mv1.1` and `mv1.2` respectively. To figure out which interfaces to bring down, you can inspect the properties of  a link in Flack and see which IP corresponds to each link and find the interface with this IP address.
     320
     321[[Image(linkdetails.png)]]
     322
     323To bring them down run :
     324{{{
     325sudo /sbin/ifconfig mv1.1 0.0.0.0
     326
     327sudo /sbin/ifconfig mv1.2 0.0.0.0
     328}}}
     329
     330Bring down IP alson on the `source` on the interface that connects to `R2`.
     331== 4b. Run Layer 2 Ping ==
     332From source try to ping `R2`. To perform a Layer 2 ping we are going to use a program that is installed on all the nodes (pingPlus) that can be downloaded [http://www.gpolab.bbn.com/local-sw/ here].
     333The command is :
     334{{{
     335sudo /local/tutorial/pingPlus/pingPlus <MAC_ADDRESS> <INTERFACE_NAME> 12345
     336}}}
     337
     338   * <MAC_ADDRESS> is the mac address of the destination host. You can figure out the mac address of `R2` the same way as we found the interface names in the previous step.     
     339   * <INTERFACE_NAME> is the interface on `source` that corresponds to the link with `R2`; it is the interface we removed the IP from on the previous step.
     340
     341Run :
     342
     343The result should look like :
     344{{{
     345[uncusr20@source ~]$ sudo /local/tutorial/pingPlus/pingPlus 02:00:9B:48:3E:20 mv1.1 12345
     346RQ:'5582+2067' to 2:0:9b:48:3e:20.
     347RQ:5582+2067 from 2:0:3e:15:6c:ab.
     348}}}
     349
     350== 4c. Enable Layer 2 forwarding at `R2` ==
     351If we try to ping PC-WashDC from source, the packets will not get through, since there is no
     352router running at `R2` that will forward the packets along. For this tutorial we have installed
     353click router on `R2`, and we are going to run a simple learning switch module. However you can
     354imagine that you can implement a more complicated routing algorithm.
     355
     356Lets generate the click configuration file. In the terminal of `R2` run:
     357{{{
     358cd
     359[inki@r2 ~]$ python /local/tutorial/makeClickConfig.py > switch.click
     360}}}
     361
     362In order to start the click router, at R2 run :
     363{{{
     364sudo /usr/local/bin/click switch.click
     365}}}
     366The MAC address of PC-WashDC is 00:1B:21:3A:D9:C9
     367
     368Then from `source`, try to ping PC-WashDC
     369{{{
     370[inki@source /local/tutorial/pingPlus]$ sudo ./pingPlus 00:1B:21:3A:D9:C9  <INTERFACE_NAME> 12345
     371}}}
     372
     373The output should look like :
     374{{{
     375[[uncusr20@source ~]$ sudo /local/tutorial/pingPlus/pingPlus 00:1B:21:3A:D9:C9 mv1.1 12345
     376RQ:'35+4503' to 0:1b:21:3a:d9:c9.
     377RQ:35+4503 from 2:0:3e:15:6c:ab.
     378}}}
     379
     380Congratulations you have run a Layer 2 experiment that spans across the United States!
     381
     382= 5. Cleanup resources =
     383Although all your reservations, have expiration times, its always good practice
     384to release the resources after your experiment is over to make them available
     385to other experimenters.
     386
     387=== 5a. Deletesliver with Omni ===
     388We are going to use Omni to release our resources, For each AM that you have used
     389you should delete your sliver. In the tutorial we used the AMs at Kentucky and at Utah.
     390
     391From the terminal that you were using to run your Omni commands, run
     392
     393{{{
     394omni.py deletesliver -a  pg-utah <slicename>
     395omni.py deletesliver -a  pg-ky <slicename>
     396}}}
     397
     398
     399You can not delete your slice. Although this will be cleaned up when it expires,
     400it should be an empty container and thus does not hold up any resources.
     401
     402Congratulations, you have finished the tutorial! Now you are ready to design and
     403run your own experiments. Don't hesitate to [mailto:help@geni.net email us] with
     404any questions you might have.
     405
     406= 6. Fill out the tutorial survey =
     407We love to hear what you think so that we can improve the tutorials in the future.
     408Please complete the [https://docs.google.com/spreadsheet/viewform?formkey=dEpqY1RVOTZQZ3RiVTBDdWdUMjV5RWc6MA#gid=0 online survey] and get a temporary GENI tatoo!
     409
     410
     411= 7. Get Your Own Account =
     412The 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 [wiki:SignMeUp get your own account] so that you can further experiment with GENI.
     413
     414= AM URL Table =
     415|| AM || Nickname ||URL ||
     416|| Utah's ProtoGENI || pg-utah || http://www.emulab.net/protogeni/xmlrpc/am ||
     417|| Kentucky's ProtoGENI || pg-ky ||https://www.uky.emulab.net/protogeni/xmlrpc/am ||
     418|| OTHER || || ||
     419|| !PlanetLab ||plc||http://www.planet-lab.org:12346 ||
     420|| GPO's ProtoGENI || pg-gpo ||http://www.pgeni.gpolab.bbn.com/protogeni/xmlrpc/am ||