wiki:FlowVisor/UpgradingTo0.8.17

Version 4 (modified by Josh Smift, 11 years ago) (diff)

--

Upgrading to FlowVisor 0.8.17

Upgrading to FlowVisor 0.8.17 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.

Before doing anything else: If you were previously storing your FV password in /etc/flowvisor/fvpasswd, move it to the new recommended location, /etc/flowvisor.passwd:

sudo mv /etc/flowvisor/fvpasswd /etc/flowvisor.passwd

If you were storing your FV password in a different file, you can move it or not, as you like. (But if you don't put it in /etc/flowvisor.passwd, you'll need to edit all the fvctl commands below.)

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.passwd 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.passwd dumpConfig /tmp/config.json 2> /dev/null && cp /tmp/config.json config.json
fvctl --passwd-file=/etc/flowvisor.passwd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
for slice in $(fvctl --passwd-file=/etc/flowvisor.passwd listSlices | awk '{print $3}' | sort); do echo "Info for slice: $slice" ; fvctl --passwd-file=/etc/flowvisor.passwd 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.passwd 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.17", as well as a line for whatever version you currently have.

Configure APT to trust the ONL signing key:

cd
wget http://updates.onlab.us/debian/onlab-repo.gpg
sudo apt-key add onlab-repo.gpg
rm onlab-repo.gpg

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.17 may delete your entire database, and the 'flowvisor' user. This section includes steps to dump 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.

Dump your current database:

fvctl --passwd-file=/etc/flowvisor.passwd dumpConfig /tmp/config.json && cp /tmp/config.json 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 config.json file, e.g. with 'sed' like this:

sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' config.json
sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' config.json
sed -i -e 's/"checkpointing": true/"checkpointing": false/' 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.

Rotate some old logs

While FV is conveniently down, rotate some old logs out of the way:

sudo mv /var/log/flowvisor/flowvisor-stderr.log /var/log/flowvisor/flowvisor-stderr.log.1
sudo mv /var/log/flowvisor/flowvisor.log /var/log/flowvisor/flowvisor.log.1
sudo gzip /var/log/flowvisor/*.log.1

If one or the other of those don't exist, you'll get an error saying as much from the appropriate 'sudo mv' command, which you can safely ignore.

Fire it up

Start up FlowVisor:

sudo service flowvisor start

Make sure it's listening:

fvctl --passwd-file=/etc/flowvisor.passwd ping pong

That should print "PONG(fvadmin): FV version=flowvisor-0.8.17::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.passwd dumpConfig config.json
fvctl --passwd-file=/etc/flowvisor.passwd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
for slice in $(fvctl --passwd-file=/etc/flowvisor.passwd listSlices | awk '{print $3}' | sort); do echo "Info for slice: $slice" ; fvctl --passwd-file=/etc/flowvisor.passwd 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.17".
  • 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.17.