Upgrading to FlowVisor 0.8.14

Upgrading 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.

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

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.

Update your APT sources entry

(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.14", 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:

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.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.

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:

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:

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/fvpasswd ping pong

That 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.