Changes between Version 1 and Version 2 of OpenFlow/FOAM


Ignore:
Timestamp:
12/13/11 11:55:27 (8 years ago)
Author:
Josh Smift
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • OpenFlow/FOAM

    v1 v2  
    33!OpenFlow aggregates in GENI are migrating to FOAM from Expedient.
    44
     5https://openflow.stanford.edu/display/DOCS/FAQ also has more information, including common error messages (for both experimenters and admins).
     6
    57= Info for experimenters =
    68
    79The following sections are mostly of interest to GENI experimenters.
    810
     11== Rspec changes ==
     12
     13Expedient used OpenFlow v1 and v2 rspecs; FOAM uses GENI v3 with the OpenFlow v3 extensions. We have a page about [wiki:HowTo/WriteOFv3Rspecs how to write OF v3 rspecs], including some examples, information about differences from OF v2, etc. If you need a hand, just drop a note to help@geni.net.
     14
     15== Aggreate Manager URL changes ==
     16
     17The Aggregate Manager URL for FOAM is generally different from the one for Expedient. FOAM rspecs typically look like this:
     18
     19{{{
     20https://foam.gpolab.bbn.com:3626/foam/gapi/1
     21}}}
     22
     23In particular, note port 3626, "/foam/gapi/1" as the pathname (the one on the end indicates GENI AM API v1), and no trailing slash.
     24
     25Expedient rspecs typically looked like this:
     26
     27{{{
     28https://expedient.gpolab.bbn.com:1443/openflow/gapi/
     29}}}
     30
     31In particular, note port 1443, "/openflow/gapi/" as the pathname, and a trailing slash.
     32
    933== Getting your sliver approved ==
    1034
    11 If you allocate a shared resource that connects to an !OpenFlow aggregate (e.g. a MyPLC plnode or ProtoGENI host), you'll typically also need to reserve some !OpenFlow resources. When you do this, your reservation request may be held for approval, and a local FOAM admin needs to approve your request before your sliver actually becomes live. The FOAM admin isn't (yet) notified of your request, so you'll usually want to contact them to ask them to opt in your sliver.
    12 
    13 If you're setting up a multi-campus topology, we recommend writing to response-team@geni.net, which will reach all of the campus FOAM admins (as well as other GENI resource admins), so everyone will know what you're doing.
    14 
    15 If you only need to create a sliver at one site, here's a list of FOAM aggregates, and contact info for the admins:
    16 
    17 || '''!OpenFlow Aggregate info page'''                   || '''FOAM admin''' ||
    18 || [wiki:GeniAggregate/ClemsonOpenFlow Clemson]          || openflow_help-L@clemson.edu ||
    19 || [wiki:GeniAggregate/GeorgiaTechOpenFlow Georgia Tech] || Russ.Clark@gatech.edu ||
    20 || [wiki:GeniAggregate/GpoLabOpenFlow GPO Lab]           || gpo-infra@geni.net ||
    21 || [wiki:GeniAggregate/IndianaOpenFlow Indiana]          || meylor@grnoc.iu.edu ||
    22 || [wiki:GeniAggregate/RutgersOpenFlow Rutgers]          || seskar@winlab.rutgers.edu ||
    23 || [wiki:GeniAggregate/StanfordOpenFlow Stanford]        || deployment-help@openflowswitch.org ||
    24 || [wiki:GeniAggregate/WashingtonOpenFlow Washington]    || balkan@cs.washington.edu ||
    25 || [wiki:GeniAggregate/WisconsinOpenFlow Wisconsin]      || agember@cs.wisc.edu ||
    26 ||                                                       || ||
    27 || [wiki:GeniAggregate/I2OpenFlow Internet2]             || geni-openflow@internet2.edu ||
    28 || [wiki:GeniAggregate/NLROpenFlow NLR]                  || openflow@nlr.net ||
     35If you allocate a shared resource that connects to an !OpenFlow aggregate (e.g. a MyPLC plnode or ProtoGENI host), you'll typically also need to reserve some !OpenFlow resources. When you do this, your reservation request may be held for approval, and a local FOAM admin needs to approve your request before your sliver actually becomes live. You should get e-mail from FOAM when your sliver is created, and another message when it's been approved; if you don't hear back, you may be able to reach a FOAM admin by replying to that message.
     36
     37If you're setting up a multi-campus topology, note that your sliver will need to be approved separately at each FOAM aggregate.
    2938
    3039= Info for admins =
     
    3241The following sections are mostly of interest to FOAM admins.
    3342
     43== Switching from Expedient to FOAM ==
     44
     45https://openflow.stanford.edu/display/DOCS/Install+Guide is the official FOAM installation guide; here are some specific notes for mesoscale campuses who are migrating from Expedient.
     46
     47You should be able to run FOAM on the same system where you're currently running Expedient, if you'd like. Conversely, if you'd like to switch to a different system, the migration is an opportune time to do that.
     48
     49We recommend having a dedicated FOAM-controlled FlowVisor; this isn't strictly necessary, but it keeps things pleasantly simple. FlowVisor and FOAM can run on the same host, which should ideally have 3 GB of RAM or more, and two or more CPUs. Fast disks also help, as FlowVisor (as of 0.8.1) can be I/O intensive. These requirements may increase for larger scale deployments.
     50
     51The binary package works well with the current Long Term Stable release of Ubuntu (10.04), and we recommend that if you don't have another preference. We're working on creating RPMs, for sites who prefer Red Hat type distributions.
     52
     53You can choose whatever you'd like as your site tag. Using the fully-qualified domain name of your FOAM server is convenient, as it allows you to use a different site tag on different servers, if you have more than one (e.g. one for testing purposes). You can also use a CNAME; for example, the GPO Lab FOAM server's hostname is tulum.gpolab.bbn.com, but we use foam.gpolab.bbn.com as our site tag (and then other tags for staging and testing instances).
     54
     55FOAM will send e-mail to both experimenters and admins when various things happen: When a sliver is created, approved, disabled, rejected, or deleted; and when a sliver is within a week of expiring, a day of expiring, and actually expires. You'll also get a message once a day with a list of slivers that are currently in the pending queue.
     56
     57We recommend using an e-mail address for the "From" setting, at installation time, which actually receives mail, so that experimenters can reach you by replying to messages from FOAM, if they need help. We use foam-admin@gpolab.bbn.com for both "From" and "Admin email", and don't set reply-to.
     58
     59You can customize the text of the messages that are sent: The default templates are in /opt/foam/etc/templates/default, and if you create a file in /opt/foam/etc/templates/custom with the same name as one of the files in .../default, the one in .../custom will take precedence. The files in .../default will be replaced when you install new versions of FOAM; anything you create in .../custom will persist through upgrades.
     60
     61You can leave Expedient running if you want, but it might be confusing. This is how we removed it in the GPO Lab:
     62
     63{{{
     64sudo apt-get remove python-optin-manager python-expedient apache2
     65sudo apt-get autoremove
     66sudo dpkg --purge apache2.2-common python-expedient
     67sudo rm -rf /usr/lib/python2.6/dist-packages/{openflow,geni,expedient,sfa,expedient_geni} /etc/{expedient,optin_manager} /etc/apt/sources.list.d/expedient.list
     68}}}
     69
     70If you have any trouble migrating, or suggestions for how to improve these docs, just drop a note to gpo-infra@bbn.com, or stop by the foam@conference.j.ir.bbn.com Jabber channel.
     71
     72If you encounter any bugs, or have improvement or feature requests, https://openflow.stanford.edu/bugs/browse/FOAM is the JIRA issue tracker for FOAM. (There's also one for FlowVisor, and other Stanford OpenFlow projects.)
     73
     74== Using foamctl ==
     75
     76https://openflow.stanford.edu/display/DOCS/foamctl+Guide is the official guide to foamctl, and describes in detail everything that it can do. Here are some specific commands that we've found useful for performing common tasks.
     77
     78These commands all assume that you're running them on the FOAM server, and that you have a file /opt/foam/etc/foampasswd, containing the FOAM admin password.
     79
     80=== Get a list of slivers ===
     81
     82Pending ones:
     83
     84{{{
     85foamctl list-slivers -s Pending --passwd-file=/opt/foam/etc/foampasswd
     86}}}
     87
     88All active ones:
     89
     90{{{
     91foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd
     92}}}
     93
     94Either of these will give you a sliver URN; if you do
     95
     96{{{
     97sliver_urn=urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+jbsstghosts:678fc69b-76e1-4a50-9fb2-ab5c4a5298d6
     98}}}
     99
     100(with the actual URN of course), the rest of these commands will then work as-is.
     101
     102Deleted ones:
     103
     104{{{
     105foamctl list-slivers -d --passwd-file=/opt/foam/etc/foampasswd
     106}}}
     107
     108=== Find a sliver from a slice name ===
     109
     110If you know a user's slice name, you can grep for it:
     111
     112{{{
     113foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+exampleslice
     114}}}
     115
     116You can use this to get a sliver URN and/or an FV slice name from a GENI slice name, assigned to $sliver_urn and $flowvisor_slice:
     117
     118{{{
     119slicename=exampleslice ; sliver_urn=$(foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+$slicename | sed -e 's/ *"sliver_urn": "\(.*\)".*/\1/') ; flowvisor_slice=$(echo $sliver_urn | awk -F : '{print $NF}')
     120}}}
     121
     122The rest of these commands assume that you've used that (or something similar) to set $sliver_urn.
     123
     124=== Show a sliver's basic info ===
     125
     126{{{
     127foamctl show-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     128}}}
     129
     130=== Show a sliver's rspec ===
     131
     132{{{
     133foamctl show-sliver -r -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     134}}}
     135
     136=== Show a sliver's flowspec ===
     137
     138{{{
     139foamctl show-sliver -s -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     140}}}
     141
     142=== Show a sliver's flowspace ===
     143
     144{{{
     145foamctl show-sliver -f -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     146}}}
     147
     148=== Approve a sliver ===
     149
     150This marks a sliver in FOAM as Approved, and adds a FV slice and flowspace rules for it to the FlowVisor.
     151
     152{{{
     153foamctl approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     154}}}
     155
     156=== Disable a sliver ===
     157
     158This marks a sliver in FOAM as Pending, and removes a FV slice and flowspace rules for it from the FlowVisor.
     159
     160{{{
     161foamctl disable-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     162}}}
     163
     164=== Reject a sliver ===
     165
     166This marks a sliver in FOAM as Rejected, and removes a FV slice and flowspace rules for it from the FlowVisor.
     167
     168{{{
     169foamctl reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     170}}}
     171
     172=== Delete a sliver ===
     173
     174This disables a sliver, and marks it as deleted, just like the GENI AM API !DeleteSliver call.
     175
     176{{{
     177foamctl delete-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     178}}}
     179
     180You should generally only do this with the experimenter's permission, and if the experimenter can't delete their own sliver for some reason, so they're not confused about where their sliver went. (If you disable or reject it, they can still see it; if you delete it, it's essentially gone forever from their point of view.)
     181
    34182== Moving orphaned Expedient-created FV slices to FOAM slivers ==
    35183
    36184If you've shut down Expedient and brought up FOAM, you may have !FlowVisor slices that were created by Expedient, which are now essentially orphaned. For each of those FV slices, its owner should create an OpenFlow v3 rspec (the format FOAM uses), and create a new sliver in FOAM. You can then verify that the new sliver looks right, manually delete their old sliver, and approve the new one.
    37185
    38 Here's an example, of migrating the jbs15 and jbs16 slivers at BBN.
     186Here's an example, showing how we migrated the jbs15 and jbs16 slivers at BBN.
    39187
    40188Check to see that the new slivers are there in FOAM, awaiting approval: