Changes between Version 2 and Version 3 of FlowVisor/UpgradingTo0.8.14


Ignore:
Timestamp:
12/27/12 20:25:47 (6 years ago)
Author:
Josh Smift
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • FlowVisor/UpgradingTo0.8.14

    v2 v3  
    1 [[PageOutline]]
     1You probably want to [wiki:FlowVisor/UpgradingTo0.8.17 upgrade to 0.8.17] instead.
    22
    3 = Upgrading to !FlowVisor 0.8.14 =
    4 
    5 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.
    6 
    7 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
    8 
    9 {{{
    10 fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json
    11 }}}
    12 
    13 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!
    14 
    15 = Common pre-install steps =
    16 
    17 First, there are some things to do regardless of which version you're upgrading from.
    18 
    19 == Capture state before the upgrade ==
    20 
    21 Get a dump of the flowspace and slice info:
    22 
    23 {{{
    24 cd
    25 rm -rf ~/tmp/flowvisor-upgrade
    26 mkdir -p ~/tmp/flowvisor-upgrade/before
    27 cd ~/tmp/flowvisor-upgrade/before
    28 
    29 fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json 2> /dev/null && cp /tmp/config.json config.json
    30 fvctl --passwd-file=/etc/flowvisor/fvpasswd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
    31 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
    32 }}}
    33 
    34 You'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 
    40 Try both of these commands:
    41 
    42 {{{
    43 fvctl --passwd-file=/etc/flowvisor/fvpasswd ping pong
    44 dpkg -s flowvisor | grep ^Version
    45 }}}
    46 
    47 Just keep track of the output for now, in case you end up wanting to know later.
    48 
    49 == Update your APT sources entry ==
    50 
    51 Update the FOAM apt sources entry, changing
    52 
    53 {{{
    54 deb http://updates.flowvisor.org/openflow/downloads/GENI/DEB unstable/binary-$(ARCH)/
    55 }}}
    56 
    57 to
    58 
    59 {{{
    60 deb 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 
    65 Make sure that worked and that it's available:
    66 
    67 {{{
    68 sudo apt-get update
    69 apt-cache show flowvisor | grep "^Version"
    70 }}}
    71 
    72 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.
    73 
    74 = Version-specific steps =
    75 
    76 Make sure you do only '''one''' of these subsections!
    77 
    78 == Upgrading from an XML-based version ==
    79 
    80 Do this subsection '''only''' if you're upgrading from an XML-based version!
    81 
    82 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.)
    83 
    84 Stop the currently running Flowvisor:
    85 
    86 {{{
    87 sudo service flowvisor stop
    88 }}}
    89 
    90 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.
    91 
    92 {{{
    93 ls -Flad /etc/flowvisor /usr/etc/flowvisor
    94 }}}
    95 
    96 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.
    97 
    98 If /etc/flowvisor is a symlink, remove it:
    99 
    100 {{{
    101 sudo rm /etc/flowvisor
    102 }}}
    103 
    104 If you now have a directory /usr/etc/flowvisor, and no /etc/flowvisor, rename the directory:
    105 
    106 {{{
    107 sudo mv /usr/etc/flowvisor /etc/flowvisor
    108 }}}
    109 
    110 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.
    111 
    112 Install the software, and remove old dependencies that aren't needed any more:
    113 
    114 {{{
    115 sudo apt-get install flowvisor
    116 sudo apt-get autoremove
    117 }}}
    118 
    119 If your /etc/flowvisor directory, and its contents, are '''not''' owned by the 'flowvisor' user, change it:
    120 
    121 {{{
    122 sudo chown flowvisor:flowvisor -Rh /etc/flowvisor
    123 }}}
    124 
    125 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):
    126 
    127 {{{
    128 sudo -u flowvisor fvconfig generate /dev/null
    129 }}}
    130 
    131 Convert your config.xml file to a config.json file
    132 
    133 {{{
    134 sudo -u flowvisor fvconfig convert /etc/flowvisor/config.xml
    135 }}}
    136 
    137 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.
    138 
    139 To do that, edit your new config.json file, e.g. with 'sed' like this:
    140 
    141 {{{
    142 sudo -u flowvisor sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' /etc/flowvisor/config.json
    143 sudo -u flowvisor sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' /etc/flowvisor/config.json
    144 sudo -u flowvisor sed -i -e 's/"checkpointing": true/"checkpointing": false/' /etc/flowvisor/config.json
    145 }}}
    146 
    147 Load it into the new database:
    148 
    149 {{{
    150 sudo -u flowvisor fvconfig load /etc/flowvisor/config.json
    151 }}}
    152 
    153 Now skip down to "Common post-install steps".
    154 
    155 == Upgrading from a DB-based version ==
    156 
    157 Do this subsection '''only''' if you're upgrading from an DB-based version!
    158 
    159 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.
    160 
    161 So, just in case, get the UID of the current 'flowvisor' user:
    162 
    163 {{{
    164 id flowvisor
    165 }}}
    166 
    167 Keep track of this UID for a later step.
    168 
    169 Back up your current database:
    170 
    171 {{{
    172 fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /etc/flowvisor/config.json
    173 }}}
    174 
    175 Stop the currently running Flowvisor:
    176 
    177 {{{
    178 sudo service flowvisor stop
    179 }}}
    180 
    181 Remove the current verson, and the old database:
    182 
    183 {{{
    184 sudo apt-get remove flowvisor
    185 sudo rm -rf /usr/share/db/flowvisor
    186 }}}
    187 
    188 Install the software, and remove old dependencies that aren't needed any more:
    189 
    190 {{{
    191 sudo apt-get install flowvisor
    192 sudo 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 
    197 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:
    198 
    199 {{{
    200 sudo chown flowvisor:flowvisor -Rh /etc/flowvisor /var/log/flowvisor /tmp/jna /tmp/config.json
    201 sudo find / -user OLDUID -print
    202 }}}
    203 
    204 where "OLDUID" is the old UID you found before.
    205 
    206 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):
    207 
    208 {{{
    209 sudo -u flowvisor fvconfig generate /dev/null
    210 }}}
    211 
    212 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.
    213 
    214 To do that, edit your new config.json file, e.g. with 'sed' like this:
    215 
    216 {{{
    217 sudo -u flowvisor sed -i -e 's/"run_topology_server": true/"run_topology_server": false/' /etc/flowvisor/config.json
    218 sudo -u flowvisor sed -i -e 's/"stats_desc_hack": true/"stats_desc_hack": false/' /etc/flowvisor/config.json
    219 sudo -u flowvisor sed -i -e 's/"checkpointing": true/"checkpointing": false/' /etc/flowvisor/config.json
    220 }}}
    221 
    222 Load it into the new database:
    223 
    224 {{{
    225 sudo -u flowvisor fvconfig load /etc/flowvisor/config.json
    226 }}}
    227 
    228 Now skip down to "Common post-install steps".
    229 
    230 = Common post-install steps =
    231 
    232 Finally, there are some things to do regardless of which version you're upgrading from.
    233 
    234 == Rotate some old logs ==
    235 
    236 While FV is conveniently down, rotate some old logs out of the way:
    237 
    238 {{{
    239 sudo mv /var/log/flowvisor/flowvisor-stderr.log /var/log/flowvisor/flowvisor-stderr.log.1
    240 sudo mv /var/log/flowvisor/flowvisor.log /var/log/flowvisor/flowvisor.log.1
    241 sudo gzip /var/log/flowvisor/*.log.1
    242 }}}
    243 
    244 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.
    245 
    246 == Fire it up ==
    247 
    248 Start up !FlowVisor:
    249 
    250 {{{
    251 sudo service flowvisor start
    252 }}}
    253 
    254 Make sure it's listening:
    255 
    256 {{{
    257 fvctl --passwd-file=/etc/flowvisor/fvpasswd ping pong
    258 }}}
    259 
    260 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.
    261 
    262 == Compare the new "after" state to the "before" state ==
    263 
    264 Get a dump of the flowspace and slice info:
    265 
    266 {{{
    267 cd
    268 rm -rf ~/tmp/foam-upgrade/after
    269 mkdir -p ~/tmp/flowvisor-upgrade/after
    270 cd ~/tmp/flowvisor-upgrade/after
    271 
    272 fvctl --passwd-file=/etc/flowvisor/fvpasswd dumpConfig /tmp/config.json && cp /tmp/config.json config.json
    273 fvctl --passwd-file=/etc/flowvisor/fvpasswd listFlowSpace | sed -re 's/id=\[[0-9\-]+\]/[id number stripped]/' > flowspace
    274 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
    275 }}}
    276 
    277 Diff the results against the "before" results:
    278 
    279 {{{
    280 cd ~/tmp/flowvisor-upgrade/before
    281 for file in * ; do diff -u $file ../after/$file ; done
    282 }}}
    283 
    284 You'll probably see some minor differences, including some or all of:
    285 
    286  * In config.json, checkpointing, stats_desc_hack, and run_topology_server changing from true to false.
    287  * In config.json, 'version changing to "flowvisor-0.8.14".
    288  * In sliceinfo and config.json, controller_port values changing.
    289  * In sliceinfo and config.json, drop_policy settings changing.
    290 
    291 None of those are cause for alarm, nor is it alarming if you ''don't'' see some of those differences.
    292 
    293 Anything beyond those is unexpected, and worth looking into with GPO and/or ONL.
    294 
    295 == Clean up ==
    296 
    297 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:
    298 
    299 {{{
    300 cp /etc/flowvisor/config.{xml,json} ~
    301 sudo -u flowvisor rm /etc/flowvisor/config.{xml,json}
    302 }}}
    303 
    304 That's it! Enjoy FV 0.8.14.
     3(In the unlikely event otherwise, you can look at old versions of this page to see the process we had tested for upgrading to 0.8.14.)