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

Timestamp:

11/27/12 00:28:34 (11 years ago)

Author:

Josh Smift

Comment:

--

FlowVisor/UpgradingTo0.8.13

@@ +1 @@
+[[PageOutline]]
+
+= Upgrading !to FlowVisor 0.8.13 =
+
+Upgrading to !FlowVisor 0.8.13 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.
+
+Identifying 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
+
+{{{
+fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json
+}}}
+
+If 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!
+
+= Common pre-install steps =
+
+First, there are some things to do regardless of which version you're upgrading from.
+
+== Capture state before the upgrade ==
+
+Get a dump of the flowspace and slice info:
+
+{{{
+cd
+rm -rf ~/tmp/flowvisor-upgrade
+mkdir -p ~/tmp/flowvisor-upgrade/before
+cd ~/tmp/flowvisor-upgrade/before
+
+fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json 2> /dev/null && cp /tmp/config.json config.json
+fvctl --passwd-file=/etc/flowvisor/fvpasswd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
+for 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
+}}}
+
+You'll diff this later against similar output from after the upgrade.
+
+(If you're running an XML-based version, the 'fvctl dumpConfig' command won't actually do anything; that's normal and expected.)
+
+== Check your current version ==
+
+Try both of these commands:
+
+{{{
+fvctl --passwd-file=/etc/flowvisor/fvpasswd ping pong
+dpkg -s flowvisor | grep ^Version
+}}}
+
+Just keep track of the output for now, in case you end up wanting to know later.
+
+== Update your APT sources entry ==
+
+Update the FOAM apt sources entry, changing
+
+{{{
+deb http://updates.flowvisor.org/openflow/downloads/GENI/DEB unstable/binary-$(ARCH)/
+}}}
+
+to
+
+{{{
+deb http://updates.onlab.us/debian stable contrib
+}}}
+
+(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.)
+
+Make sure that worked and that it's available:
+
+{{{
+sudo apt-get update
+apt-cache show flowvisor | grep "^Version"
+}}}
+
+The output of the second command should include a line saying "Version: 0.8.13", as well as a line for whatever version you currently have.
+
+= Version-specific steps =
+
+Make sure you do only '''one''' of these subsections!
+
+== Upgrading from an XML-based version ==
+
+Do this subsection '''only''' if you're upgrading from an XML-based version!
+
+Upgrading 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.)
+
+Stop the currently running Flowvisor:
+
+{{{
+sudo service flowvisor stop
+}}}
+
+Check 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.
+
+{{{
+ls -Flad /etc/flowvisor /usr/etc/flowvisor
+}}}
+
+If 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.
+
+If /etc/flowvisor is a symlink, remove it:
+
+{{{
+sudo rm /etc/flowvisor
+}}}
+
+If you now have a directory /usr/etc/flowvisor, and no /etc/flowvisor, rename the directory:
+
+{{{
+sudo mv /usr/etc/flowvisor /etc/flowvisor
+}}}
+
+At 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.
+
+Install the software, and remove old dependencies that aren't needed any more:
+
+{{{
+sudo apt-get install flowvisor
+sudo apt-get autoremove
+}}}
+
+If your /etc/flowvisor directory, and its contents, are '''not''' owned by the 'flowvisor' user, change it:
+
+{{{
+sudo chown flowvisor:flowvisor -Rh /etc/flowvisor
+}}}
+
+Generate 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):
+
+{{{
+sudo -u flowvisor fvconfig generate /dev/null
+}}}
+
+Convert your config.xml file to a config.json file
+
+{{{
+sudo -u flowvisor fvconfig convert /etc/flowvisor/config.xml
+}}}
+
+There 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.
+
+To do that, edit your new config.json file, e.g. with 'sed' like this:
+
+{{{
+sudo -u flowvisor sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' /etc/flowvisor/config.json
+sudo -u flowvisor sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' /etc/flowvisor/config.json
+sudo -u flowvisor sed -i -e 's/"checkpointing": true/"checkpointing": false/' /etc/flowvisor/config.json
+}}}
+
+Load it into the new database:
+
+{{{
+sudo -u flowvisor fvconfig load /etc/flowvisor/config.json
+}}}
+
+Now skip down to "Common post-install steps".
+
+== Upgrading from a DB-based version ==
+
+Do this subsection '''only''' if you're upgrading from an DB-based version!
+
+Upgrading from a DB version prior to 0.8.13 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.
+
+So, just in case, get the UID of the current 'flowvisor' user:
+
+{{{
+id flowvisor
+}}}
+
+Keep track of this UID for a later step.
+
+Back up your current database:
+
+{{{
+fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /etc/flowvisor/config.json
+}}}
+
+Stop the currently running Flowvisor:
+
+{{{
+sudo service flowvisor stop
+}}}
+
+Remove the current verson, and the old database:
+
+{{{
+sudo apt-get remove flowvisor
+sudo rm -rf /usr/share/db/flowvisor
+}}}
+
+Install the software, and remove old dependencies that aren't needed any more:
+
+{{{
+sudo apt-get install flowvisor
+sudo apt-get autoremove
+}}}
+
+(There may not be any old dependencies, in which case the second command won't do anything; that's fine.)
+
+If 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:
+
+{{{
+sudo chown flowvisor:flowvisor -Rh /etc/flowvisor /var/log/flowvisor /tmp/jna /tmp/config.json
+sudo find / -user OLDUID -print
+}}}
+
+where "OLDUID" is the old UID you found before.
+
+Generate 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):
+
+{{{
+sudo -u flowvisor fvconfig generate /dev/null
+}}}
+
+There 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.
+
+To do that, edit your new config.json file, e.g. with 'sed' like this:
+
+{{{
+sudo -u flowvisor sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' /etc/flowvisor/config.json
+sudo -u flowvisor sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' /etc/flowvisor/config.json
+sudo -u flowvisor sed -i -e 's/"checkpointing": true/"checkpointing": false/' /etc/flowvisor/config.json
+}}}
+
+Load it into the new database:
+
+{{{
+sudo -u flowvisor fvconfig load /etc/flowvisor/config.json
+}}}
+
+Now skip down to "Common post-install steps".
+
+= Common post-install steps =
+
+Finally, there are some things to do regardless of which version you're upgrading from.
+
+== Fire it up ==
+
+Start up !FlowVisor:
+
+{{{
+sudo service flowvisor start
+}}}
+
+Make sure it's listening:
+
+{{{
+fvctl --passwd-file=/etc/flowvisor/fvpasswd ping pong
+}}}
+
+That should print "PONG(fvadmin): FV version=flowvisor-0.8.13::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.
+
+== Compare the new "after" state to the "before" state ==
+
+Get a dump of the flowspace and slice info:
+
+{{{
+cd
+rm -rf ~/tmp/foam-upgrade/after
+mkdir -p ~/tmp/flowvisor-upgrade/after
+cd ~/tmp/flowvisor-upgrade/after
+
+fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json && cp /tmp/config.json config.json
+fvctl --passwd-file=/etc/flowvisor/fvpasswd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
+for 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
+}}}
+
+Diff the results against the "before" results:
+
+{{{
+cd ~/tmp/flowvisor-upgrade/before
+for file in * ; do diff -u $file ../after/$file ; done
+}}}
+
+You'll probably see some minor differences, including some or all of:
+
+ * In config.json, checkpointing, stats_desc_hack, and run_topology_server changing from true to false.
+ * In config.json, 'version changing to "flowvisor-0.8.13".
+ * In sliceinfo and config.json, controller_port values changing.
+ * In sliceinfo and config.json, drop_policy settings changing.
+
+None of those are cause for alarm, nor is it alarming if you ''don't'' see some of those differences.
+
+Anything beyond those is unexpected, and worth looking into with GPO and/or ONL.
+
+== Clean up ==
+
+Once 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:
+
+{{{
+cp /etc/flowvisor/config.{xml,json} ~
+sudo -u flowvisor rm /etc/flowvisor/config.{xml,json}
+}}}
+
+That's it! Enjoy FV 0.8.13.