Changes between Version 22 and Version 23 of OpenFlow/FOAM


Ignore:
Timestamp:
07/17/12 11:28:52 (12 years ago)
Author:
Josh Smift
Comment:

Major update for FOAM 0.8

Legend:

Unmodified
Added
Removed
Modified

  • OpenFlow/FOAM

    v22 v23  
    55FOAM is an OpenFlow aggregate manager, which sites in GENI use to allow experimenters to allocate !OpenFlow resources.
    66
    7 https://openflow.stanford.edu/display/FOAM has more information about FOAM (from the official site at Stanford), including [https://openflow.stanford.edu/display/FOAM/Install+Guide installation instructions], [https://openflow.stanford.edu/display/FOAM/FAQ a FAQ] with common error messages (for both experimenters and admins), etc.
     7https://openflow.stanford.edu/display/FOAM has more information about FOAM (from the official site at Stanford), including [https://openflow.stanford.edu/display/FOAM/0.8.x+Install+Guide installation instructions], [https://openflow.stanford.edu/display/FOAM/FAQ a FAQ] with common error messages (for both experimenters and admins), etc.
    88
    99= Info for experimenters =
    … …  
    1717== Getting your sliver approved ==
    1818
    19 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. 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.
    20 
    21 Make sure that you also provide a '''valid email address''' in your rspec so that you can get the notifications about status changes of your !OpenFlow sliver.   
     19If 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, in which case a local FOAM admin will need 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 (or to the contact information in the body of the message).
     20
     21As of FOAM 0.8, FOAM can read your e-mail address from your slice credential. If that address is valid, then you don't need to include an e-mail address in your rspec, but make sure it is! If it isn't, make sure that you also provide a valid email address in your rspec so that you can get the notifications about status changes of your !OpenFlow sliver.
    2222
    2323If you're setting up a multi-campus topology, note that your sliver will need to be approved separately at each FOAM aggregate.
    … …  
    2929== Version ==
    3030
    31 The GPO currently recommends version 0.6.4 (the latest stable release) for GENI sites.
     31The GPO currently recommends version 0.8.1 (the latest stable release) for GENI sites. There are many changes from 0.8 to 0.6, and we recommend working with the GPO to help the upgrade process go smoothly. Contact us at gpo-infra@geni.net and we'll be happy to help!
     32
     33NOTE that much of this page is FOAM 0.8 specific. http://groups.geni.net/geni/wiki/OpenFlow/FOAM?version=22 has the last 0.6 specific version.
    3234
    3335== Advisories ==
    3436
    3537Here are some things that FOAM admins should be aware of and watch out for.
    36 
    37 === Administrative list-resources blocks other FOAM operations ===
    38 
    39 In FOAM 0.6, an administrative list-resources call locks the FOAM database, and thus blocks other FOAM operations. If an experimenter tries to use FOAM while this is happening, they'll get a "database is locked" error; if they retry, it should work. (If the error persists, something else is probably wrong.)
    40 
    41 The FOAM monitoring code (from the 'tango-monitor-foam' package) does an administrative list-slivers whenever it runs, and it runs once per minute by default, so there's small window each minute (a second or two) when this can happen.
    42 
    43 This issue is being tracked in [https://openflow.stanford.edu/bugs/browse/FOAM-227 JIRA ticket FOAM-227], and should be fixed in FOAM 0.8.
    4438
    4539=== Rspecs that include both cross-connect ports ===
    … …  
    5953
    6054We don't currently think that there's a valid use case for an experimenter wanting to specify a match at one layer without specifying the protocol at a lower layer, but will amend this advisory if we encounter one.
     55
     56=== Administrative list-resources blocks other FOAM operations ===
     57
     58In FOAM 0.6, an administrative list-resources call locks the FOAM database, and thus blocks other FOAM operations. If an experimenter tries to use FOAM while this is happening, they'll get a "database is locked" error; if they retry, it should work. (If the error persists, something else is probably wrong.)
     59
     60The FOAM monitoring code (from the 'tango-monitor-foam' package) does an administrative list-slivers whenever it runs, and it runs once per minute by default, so there's small window each minute (a second or two) when this can happen.
     61
     62This issue is fixed in FOAM 0.8.
    6163
    6264== Sliver approval workflow ==
    … …  
    8587
    8688{{{
    87 foamctl approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     89foamctl geni:approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    8890}}}
    8991
    … …  
    9193
    9294{{{
    93 foamctl reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     95foamctl geni:reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    9496}}}
    9597
    … …  
    100102== Managing FOAM slivers ==
    101103
    102 https://openflow.stanford.edu/display/FOAM/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.
     104https://openflow.stanford.edu/display/FOAM/foamctl+Guide is the official guide to foamctl, and describes in detail everything that it can do. (NOTE: As of 2012-07-17, this guide was FOAM 0.6 specific, and marked as a "legacy document". [https://openflow.stanford.edu/bugs/browse/FOAM-160 FOAM-160] is tracking the task of updating it.)
     105
     106Here are some specific commands that we've found useful for performing common tasks.
    103107
    104108These 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.
    … …  
    106110=== Get a list of slivers ===
    107111
    108 Pending ones:
    109 
    110 {{{
    111 foamctl list-slivers -s Pending --passwd-file=/opt/foam/etc/foampasswd
     112Pending ones (this is essentially "the queue" of slivers that are awaiting admin action):
     113
     114{{{
     115foamctl geni:list-slivers -s Pending --passwd-file=/opt/foam/etc/foampasswd
    112116}}}
    113117
    … …  
    115119
    116120{{{
    117 foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd
     121foamctl geni:list-slivers --passwd-file=/opt/foam/etc/foampasswd
    118122}}}
    119123
    … …  
    124128}}}
    125129
    126 (with the actual URN of course), the rest of these commands will then work as-is.
     130(with the actual URN of course), the rest of these commands will then work as-is -- or you can find a sliver from a slice name, see below.
    127131
    128132Deleted ones:
    129133
    130134{{{
    131 foamctl list-slivers -d --passwd-file=/opt/foam/etc/foampasswd
     135foamctl geni:list-slivers --deleted --passwd-file=/opt/foam/etc/foampasswd
    132136}}}
    133137
    … …  
    137141
    138142{{{
    139 foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+exampleslice
     143foamctl geni:list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+exampleslice
    140144}}}
    141145
    … …  
    143147
    144148{{{
    145 slicename=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}')
    146 }}}
     149slicename=exampleslice ; sliver_urn=$(foamctl geni: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}')
     150}}}
     151
     152Replace "exampleslice" with a string to egrep for. Choose something that's unique to the slice; note that if the string contains egrep regexp type characters, like * or +, you'll need to backslash those.
    147153
    148154The rest of these commands assume that you've used that (or something similar) to set $sliver_urn.
    … …  
    151157
    152158{{{
    153 foamctl show-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     159foamctl geni:show-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    154160}}}
    155161
    … …  
    157163
    158164{{{
    159 foamctl show-sliver -r -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     165foamctl geni:show-sliver -r -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    160166}}}
    161167
    … …  
    163169
    164170{{{
    165 foamctl show-sliver -s -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     171foamctl geni:show-sliver -s -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    166172}}}
    167173
    … …  
    169175
    170176{{{
    171 foamctl show-sliver -f -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     177foamctl geni:show-sliver -f -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    172178}}}
    173179
    174180=== Approve a sliver ===
    175181
    176 This marks a sliver in FOAM as Approved, and adds a FV slice and flowspace rules for it to the !FlowVisor.
    177 
    178 {{{
    179 foamctl approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     182This marks a sliver in FOAM as Pending, and adds its FV slice and flowspace rules for it to the !FlowVisor (if it wasn't already).
     183
     184{{{
     185foamctl geni:approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    180186}}}
    181187
    182188=== Disable a sliver ===
    183189
    184 This marks a sliver in FOAM as Pending, and removes a FV slice and flowspace rules for it from the !FlowVisor.
    185 
    186 {{{
    187 foamctl disable-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     190This marks a sliver in FOAM as Pending, and removes its FV slice and flowspace rules for it from the !FlowVisor (if there were any).
     191
     192{{{
     193foamctl geni:disable-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    188194}}}
    189195
    190196=== Reject a sliver ===
    191197
    192 This marks a sliver in FOAM as Rejected, and removes a FV slice and flowspace rules for it from the !FlowVisor.
    193 
    194 {{{
    195 foamctl reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     198This marks a sliver in FOAM as Rejected, and removes its FV slice and flowspace rules for it from the !FlowVisor (if there were any).
     199
     200{{{
     201foamctl geni:reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    196202}}}
    197203
    198204=== Delete a sliver ===
    199205
    200 This disables a sliver, and marks it as deleted, just like the GENI AM API !DeleteSliver call.
    201 
    202 {{{
    203 foamctl delete-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
     206This disables a sliver, and marks it as deleted, just like the GENI AM API !DeleteSliver call, and removes its FV slice and flowspace rules for it from the !FlowVisor (if there were any).
     207
     208{{{
     209foamctl geni:delete-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd
    204210}}}
    205211
    … …  
    214220oldsliver=<old sliver URN>
    215221newsliver=<new sliver URN>
    216 foamctl show-sliver -s -u $oldsliver --passwd-file=/opt/foam/etc/foampasswd > old.txt
    217 foamctl show-sliver -s -u $newsliver --passwd-file=/opt/foam/etc/foampasswd > new.txt
     222foamctl geni:show-sliver -r -u $oldsliver --passwd-file=/opt/foam/etc/foampasswd > old.txt
     223foamctl geni:show-sliver -r -u $newsliver --passwd-file=/opt/foam/etc/foampasswd > new.txt
    218224diff -u old.txt new.txt
    219225}}}
    … …  
    221227In the case of someone who deleted and then re-created a sliver, you could get the sliver URNs from the e-mail from FOAM, for example.
    222228
    223 We use 'show-sliver -s' because '-r' doesn't work at all on deleted slivers; and '-f' includes a priority value for approved slivers but not non-approved slivers, which clutters up the diff.
     229You can also use 'geni:show-sliver -s' to show flowspaces instead, which have the advantage of not including any comments or other formatting in the experimenter's rspec, but are a less familiar format for most admins.
    224230
    225231== Slice Authority trust configuration ==
    … …  
    228234
    229235{{{
    230 sudo foamctl bundle-certs
     236sudo foamctl geni:bundle-certs
    231237sudo service foam restart
    232238sudo service nginx restart
    … …  
    235241In particular, GENI mesoscale deployments should trust the pgeni.gpolab.bbn.com SA; the official FOAM installation guide includes this step, or you can get the cert from http://www.pgeni.gpolab.bbn.com/ca-cert/pgeni.gpolab.bbn.com.pem if you need it.
    236242
    237 == Changing FlowVisor password in FOAM ==
    238 
    239 FOAM's database stores information about FV, including its hostname and password.  If you want to change FV's password, you need to change it both in FV itself, and also in FOAM.
    240  * Change the password in FlowVisor: this assumes `/etc/flowvisor/config.xml` FlowVisor's config, and is owned by user `openflow`:
    241    * Change the password in flowvisor's config:
     243== Changing the !FlowVisor password ==
     244
     245FOAM's database stores information about the !FlowVisor it manages, including its hostname and password. If you want to change that !FlowVisor's password, you need to change it both in FV itself, and also in FOAM.
     246
     247 * Change the password in !FlowVisor: this assumes `/etc/flowvisor/config.xml` !FlowVisor's config, and is owned by user `openflow`:
     248   * Change the password in !FlowVisor's config:
    242249{{{
    243250$ sudo service flowvisor stop
    … …  
    251258$ sudo vi /etc/flowvisor/fvpasswd
    252259}}}
    253  * Change the password in FOAM.  Future versions of foamctl will support the `config:set-flowvisor-info` command.  If you are running foam-0.6.3, that command doesn't exist yet, so you'll need to use a helper script which invokes curl to talk to FOAM:
    254    * Copy the script `change_foam_fvinfo.py` from [https://openflow.stanford.edu/display/FOAM/Scripts+for+admins] on your foam
    255    * Ask FOAM for the current FlowVisor information, so you can set any fields you do not want to change to the same values again:
    256 {{{
    257 $ foamctl get-config --key="flowvisor_info" --passwd-file=/opt/foam/etc/foampasswd
    258 {
    259  "value": {
    260   "passwd": "<old_fv_passwd>",
    261   "xmlrpc_port": 8080,
    262   "host": "<old_fv_host>",
    263   "json_port": 8081
    264  }
    265 }
    266 }}}
    267    * Invoke that script to set FOAM's FlowVisor info the same way you would on an initial install:
    268 {{{
    269 $ python change_foam_fvinfo.py --passwd-file=/opt/foam/etc/foampasswd
    270 FlowVisor Hostname: <old_fv_host>
    271 FlowVisor XMLRPC Port [8080]:
    272 FlowVisor JSON RPC Port [8081]:
    273 fvadmin user password:
    274 {
    275  "status": "success"
    276 }
    277 }}}
    278    * Restart FOAM:
    279 {{{
    280 $ sudo service foam restart
     260 * Change the password in FOAM:
     261{{{
     262foamctl config:set-value --key="flowvisor.passwd" --value="$(cat /etc/flowvisor/fvpasswd)" --passwd-file=/opt/foam/etc/foampasswd
    281263}}}
    282264