Changes between Initial Version and Version 1 of FlowVisor/UpgradingTo0.8.14


Ignore:
Timestamp:
12/10/12 18:13:17 (9 years ago)
Author:
Josh Smift
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • FlowVisor/UpgradingTo0.8.14

    v1 v1  
     1[[PageOutline]]
     2
     3= Upgrading to !FlowVisor 0.8.14 =
     4
     5Upgrading to !FlowVisor 0.8.14 is slightly tricky, because the process is different depending whether your current configuration is in a database, or in a flat XML file. FV 0.8.2 and earlier used a flat XML file; 0.8.3 and later use a database.
     6
     7Identifying which version of !FlowVisor you have now can be slightly tricky, because 'fvctl ping' gives incorrect results in some versions. One reliable way to tell is whether 'fvctl dumpConfig' command works: Try
     8
     9{{{
     10fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json
     11}}}
     12
     13If that says "command 'dumpConfig' does not exist" (and prints a long usage message), you have an XML-based version. If it creates a JSON version of your FV configuration, you have a DB-based version. Follow the appropriate subsection in the "Upgrade the software" section below!
     14
     15= Common pre-install steps =
     16
     17First, there are some things to do regardless of which version you're upgrading from.
     18
     19== Capture state before the upgrade ==
     20
     21Get a dump of the flowspace and slice info:
     22
     23{{{
     24cd
     25rm -rf ~/tmp/flowvisor-upgrade
     26mkdir -p ~/tmp/flowvisor-upgrade/before
     27cd ~/tmp/flowvisor-upgrade/before
     28
     29fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json 2> /dev/null && cp /tmp/config.json config.json
     30fvctl --passwd-file=/etc/flowvisor/fvpasswd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
     31for slice in $(fvctl --passwd-file=/etc/flowvisor/fvpasswd listSlices | awk '{print $3}' | sort); do echo "Info for slice: $slice" ; fvctl --passwd-file=/etc/flowvisor/fvpasswd getSliceInfo $slice | egrep -v ^connection_[0-9]+= | sort ; done > sliceinfo
     32}}}
     33
     34You'll diff this later against similar output from after the upgrade.
     35
     36(If you're running an XML-based version, the 'fvctl dumpConfig' command won't actually do anything; that's normal and expected.)
     37
     38== Check your current version ==
     39
     40Try both of these commands:
     41
     42{{{
     43fvctl --passwd-file=/etc/flowvisor/fvpasswd ping pong
     44dpkg -s flowvisor | grep ^Version
     45}}}
     46
     47Just keep track of the output for now, in case you end up wanting to know later.
     48
     49== Update your APT sources entry ==
     50
     51Update the FOAM apt sources entry, changing
     52
     53{{{
     54deb http://updates.flowvisor.org/openflow/downloads/GENI/DEB unstable/binary-$(ARCH)/
     55}}}
     56
     57to
     58
     59{{{
     60deb http://updates.onlab.us/debian stable contrib
     61}}}
     62
     63(This is a little vague because you might have this entry in /etc/apt/sources.list, or /etc/apt/sources.list.d/<something>, or some other place. But probably one of those two.)
     64
     65Make sure that worked and that it's available:
     66
     67{{{
     68sudo apt-get update
     69apt-cache show flowvisor | grep "^Version"
     70}}}
     71
     72The output of the second command should include a line saying "Version: 0.8.14", as well as a line for whatever version you currently have.
     73
     74= Version-specific steps =
     75
     76Make sure you do only '''one''' of these subsections!
     77
     78== Upgrading from an XML-based version ==
     79
     80Do this subsection '''only''' if you're upgrading from an XML-based version!
     81
     82Upgrading from an XML version requires you to convert the flat XML configuration file into FV's new database format. (Or you can throw away your current !FlowVisor state, if you're really really sure that you don't care about any of it, but you probably don't want to do that.)
     83
     84Stop the currently running Flowvisor:
     85
     86{{{
     87sudo service flowvisor stop
     88}}}
     89
     90Check whether you currently have /etc/flowvisor, /usr/etc/flowvisor, or both, and what user owns them -- if it's '''not''' 'flowvisor', remember this fact, because there will be an additional important step later.
     91
     92{{{
     93ls -Flad /etc/flowvisor /usr/etc/flowvisor
     94}}}
     95
     96If you don't have either /etc/flowvisor or /usr/etc/flowvisor, something is probably amiss; get GPO and/or ONL involved to help figure out what's going on.
     97
     98If /etc/flowvisor is a symlink, remove it:
     99
     100{{{
     101sudo rm /etc/flowvisor
     102}}}
     103
     104If you now have a directory /usr/etc/flowvisor, and no /etc/flowvisor, rename the directory:
     105
     106{{{
     107sudo mv /usr/etc/flowvisor /etc/flowvisor
     108}}}
     109
     110At the end of all that, you should have your existing config directory in /etc/flowvisor. If it's '''not''' owned by the 'flowivsor' user, remember this -- there will be an additional important step later.
     111
     112Install the software, and remove old dependencies that aren't needed any more:
     113
     114{{{
     115sudo apt-get install flowvisor
     116sudo apt-get autoremove
     117}}}
     118
     119If your /etc/flowvisor directory, and its contents, are '''not''' owned by the 'flowvisor' user, change it:
     120
     121{{{
     122sudo chown flowvisor:flowvisor -Rh /etc/flowvisor
     123}}}
     124
     125Generate a new FV database (just hit return when prompted for a password, this will be overwritten by the next step; and ignore the "keytool error" error, it's just telling you that you already have a key pair):
     126
     127{{{
     128sudo -u flowvisor fvconfig generate /dev/null
     129}}}
     130
     131Convert your config.xml file to a config.json file
     132
     133{{{
     134sudo -u flowvisor fvconfig convert /etc/flowvisor/config.xml
     135}}}
     136
     137There are three !FlowVisor variables that are off by default in new installations, but may be on in upgraded ones, which we recommend that you turn off: run_topology_server, stats_desc_hack, and checkpointing.
     138
     139To do that, edit your new config.json file, e.g. with 'sed' like this:
     140
     141{{{
     142sudo -u flowvisor sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' /etc/flowvisor/config.json
     143sudo -u flowvisor sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' /etc/flowvisor/config.json
     144sudo -u flowvisor sed -i -e 's/"checkpointing": true/"checkpointing": false/' /etc/flowvisor/config.json
     145}}}
     146
     147Load it into the new database:
     148
     149{{{
     150sudo -u flowvisor fvconfig load /etc/flowvisor/config.json
     151}}}
     152
     153Now skip down to "Common post-install steps".
     154
     155== Upgrading from a DB-based version ==
     156
     157Do this subsection '''only''' if you're upgrading from an DB-based version!
     158
     159Upgrading from a DB version prior to 0.8.14 may delete your entire database, and the 'flowvisor' user. This section includes steps to back up and restore the DB; the new version will re-create the 'flowvisor' user, but if it gets a different UID than it had before, you may also have to fix up some permissions on various files and directories.
     160
     161So, just in case, get the UID of the current 'flowvisor' user:
     162
     163{{{
     164id flowvisor
     165}}}
     166
     167Keep track of this UID for a later step.
     168
     169Back up your current database:
     170
     171{{{
     172fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /etc/flowvisor/config.json
     173}}}
     174
     175Stop the currently running Flowvisor:
     176
     177{{{
     178sudo service flowvisor stop
     179}}}
     180
     181Remove the current verson, and the old database:
     182
     183{{{
     184sudo apt-get remove flowvisor
     185sudo rm -rf /usr/share/db/flowvisor
     186}}}
     187
     188Install the software, and remove old dependencies that aren't needed any more:
     189
     190{{{
     191sudo apt-get install flowvisor
     192sudo apt-get autoremove
     193}}}
     194
     195(There may not be any old dependencies, in which case the second command won't do anything; that's fine.)
     196
     197If your /etc/flowvisor directory, and its contents, are '''not''' owned by the 'flowvisor' user, change it, and also some other places where !FlowVisor stores files, and check for any other stray files owned by the old UID:
     198
     199{{{
     200sudo chown flowvisor:flowvisor -Rh /etc/flowvisor /var/log/flowvisor /tmp/jna /tmp/config.json
     201sudo find / -user OLDUID -print
     202}}}
     203
     204where "OLDUID" is the old UID you found before.
     205
     206Generate a new FV database (just hit return when prompted for a password, this will be overwritten by the next step; and ignore the "keytool error" error, it's just telling you that you already have a key pair):
     207
     208{{{
     209sudo -u flowvisor fvconfig generate /dev/null
     210}}}
     211
     212There are three !FlowVisor variables that are off by default in new installations, but may be on in upgraded ones, which we recommend that you turn off: run_topology_server, stats_desc_hack, and checkpointing.
     213
     214To do that, edit your new config.json file, e.g. with 'sed' like this:
     215
     216{{{
     217sudo -u flowvisor sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' /etc/flowvisor/config.json
     218sudo -u flowvisor sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' /etc/flowvisor/config.json
     219sudo -u flowvisor sed -i -e 's/"checkpointing": true/"checkpointing": false/' /etc/flowvisor/config.json
     220}}}
     221
     222Load it into the new database:
     223
     224{{{
     225sudo -u flowvisor fvconfig load /etc/flowvisor/config.json
     226}}}
     227
     228Now skip down to "Common post-install steps".
     229
     230= Common post-install steps =
     231
     232Finally, there are some things to do regardless of which version you're upgrading from.
     233
     234== Fire it up ==
     235
     236Start up !FlowVisor:
     237
     238{{{
     239sudo service flowvisor start
     240}}}
     241
     242Make sure it's listening:
     243
     244{{{
     245fvctl --passwd-file=/etc/flowvisor/fvpasswd ping pong
     246}}}
     247
     248That should print "PONG(fvadmin): FV version=flowvisor-0.8.14::pong". If you get a "connection refused" error, wait a few more seconds and try again. It shouldn't take more than 30 seconds or a minute to start up; if it's still not working after that long, something has gone wrong, and you should probably get GPO and/or ONL involved to help.
     249
     250== Compare the new "after" state to the "before" state ==
     251
     252Get a dump of the flowspace and slice info:
     253
     254{{{
     255cd
     256rm -rf ~/tmp/foam-upgrade/after
     257mkdir -p ~/tmp/flowvisor-upgrade/after
     258cd ~/tmp/flowvisor-upgrade/after
     259
     260fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json && cp /tmp/config.json config.json
     261fvctl --passwd-file=/etc/flowvisor/fvpasswd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
     262for slice in $(fvctl --passwd-file=/etc/flowvisor/fvpasswd listSlices | awk '{print $3}' | sort); do echo "Info for slice: $slice" ; fvctl --passwd-file=/etc/flowvisor/fvpasswd getSliceInfo $slice | egrep -v ^connection_[0-9]+= | sort ; done > sliceinfo
     263}}}
     264
     265Diff the results against the "before" results:
     266
     267{{{
     268cd ~/tmp/flowvisor-upgrade/before
     269for file in * ; do diff -u $file ../after/$file ; done
     270}}}
     271
     272You'll probably see some minor differences, including some or all of:
     273
     274 * In config.json, checkpointing, stats_desc_hack, and run_topology_server changing from true to false.
     275 * In config.json, 'version changing to "flowvisor-0.8.14".
     276 * In sliceinfo and config.json, controller_port values changing.
     277 * In sliceinfo and config.json, drop_policy settings changing.
     278
     279None of those are cause for alarm, nor is it alarming if you ''don't'' see some of those differences.
     280
     281Anything beyond those is unexpected, and worth looking into with GPO and/or ONL.
     282
     283== Clean up ==
     284
     285Once you're confident that this is all working as expected, make a backup copy of your configs just in case, and remove them from /etc/flowvisor:
     286
     287{{{
     288cp /etc/flowvisor/config.{xml,json} ~
     289sudo -u flowvisor rm /etc/flowvisor/config.{xml,json}
     290}}}
     291
     292That's it! Enjoy FV 0.8.14.