The upgrade and downgrade process on Steelhead appliances is not always straightforward. The following restrictions and caveats are in place:
You can only downgrade to RiOS versions which you have had installed on the Steelhead appliance. So if a certain Steelhead appliance comes installed with RiOS 5.0.6 and you have upgraded via 5.5.3, 6.0.1, 6.1.0 to 6.5.0, then you can only downgrade to these four versions.
Use the command
show version history
to see the list of previous installed RiOS versions.
Figure 5.48. Output of "show version history": Upgrade to 6.1.5, then downgrade to 6.1.4
SH # show version history Firstboot to rbt_sh 6.1.4 #92_4 2011-06-08 15:54:25 x86_64 root@palermo0:svn://svn/mgmt/br \ anches/cook_92_fix_branch on Tue Dec 6 05:33:28 GMT 2011 Upgraded to rbt_sh 6.1.5 #104_8 2011-09-29 15:26:28 x86_64 root@athens:svn://svn/mgmt/bran \ ches/cook_104_fix_branch on Wed Feb 1 23:30:34 GMT 2012 Downgraded to rbt_sh 6.1.4 #92_4 2011-06-08 15:54:25 x86_64 root@palermo0:svn://svn/mgmt/b \ ranches/cook_92_fix_branch on Thu Feb 1 23:33:28 GMT 2012
When a Steelhead appliance gets upgraded, the latest configuration file used on that software version will be saved. When a Steelhead appliance gets downgraded, it will restart from that saved configuration. So if network configurations like the IP address of the in-path interface have been changed, after the move to the current version, that IP address will be changed back to the old IP address.
A Steelhead appliance can only be upgraded to a software version which is released later, time wise, than the current one. So an upgrade from 5.5.9 to 6.0.0 is not allowed because 5.5.9 had been released later than 6.0.0 had been released.
In general, when upgrading a Steelhead appliance to a new branch, for example from 5.0.x to 6.1.x, all branches should be touched. So the Steelhead appliance needs to be upgraded to 5.5.x and 6.0.x before the upgrade to 6.1.x can be done.
The Software Upgrade Path Tool on the Riverbed Support website will tell which intermediate software versions can be used to upgrade between two branches.
There are several RiOS releases which are certified for direct upgrades, which mean that they can be upgraded to a different branch than the next one. To find out which ones, search the Riverbed Support KB system for "RiOS Direct Upgrade".
When the Steelhead appliance is running RSP, the recommendation is to disable RSP before doing the upgrades and to install the correct version of RSP image at the end. After that RSP can be enabled again.
The steps in the upgrade process are the installation of the upgrade image on the spare boot partition and, after a reboot into the new boot partition, the upgrade of the current configuration into the new software is performed.
To perform the RiOS upgrade from the CLI, issue the following commands. This example assumes that the image can be retrieved from the web server images.example.com.
Figure 5.49. Manual upgrade via the CLI, new image installed on partition 1
SH # show images [...] Last boot partition: 2 Next boot partition: 2 SH # image fetch http://images.example.com/rios/sh-5.5.3-i386.img SH # image install sh-5.5.3-i386.img 1 SH # config term SH (config) # image boot 1 SH (config) # write memory SH (config) # reload
If a downgrade is not possible because the downgrade image has never been installed before, it will fail with the following error:
Figure 5.50. Downgrade was unsuccessful
localhost mgmtd[6353]: [mgmtd.NOTICE]: Downgrade fallback in progress. localhost mgmtd[6353]: [mgmtd.NOTICE]: Downgrade fallback file /config/db/working-PROD-rbt \ sh-VER-54b74c06 doesn't exist. Looking for the most recent file with version hash 54b7 \ 4c06. localhost mgmtd[6353]: [mgmtd.ERR]: db & reg version hash mismatch, could not fallback eit \ her. possibly due to module removed without upgrade rule localhost mgmtd[6353]: [mgmtd.NOTICE]: Downgrade: could not find file for working with ver \ sion hash 54b74c06 to downgrade to. localhost mgmtd[6353]: [mgmtd.WARNING]: Configuration 'working' is damaged! localhost mgmtd[6353]: [mgmtd.NOTICE]: mgmtd exiting at 2013/11/12 22:23:23 with code 1401 \ 0 localhost mdinit: failed. localhost mdinit: Forcing reboot from fallback image 1
To force a downgrade to a RiOS version which has not been installed
before, use the commands
image install <image> <partition> force
and
image boot <partition> force
.
This will wipe the configuration including the license keys, so
make sure to keep a copy of them. Also make sure to clear the data
store afterwards, because a proper downgrade has not been performed.
The
force
in the
image install
command skips the check to see if the image to be installed is
newer than the current image during the installation phase.
The
force
in the
image boot
command skips the check to see there is a saved configuration
available for the new version during the downgrade phase.
After an upgrade, new features are often disabled by default. Because
the configuration displayed with the command
show running-config
doesn't show the configuration lines which still have their default
values, the new features will often not show up. If during a later
upgrade that feature becomes enabled by default, the configuration
on the Steelhead appliance will show this feature to be disabled.
Table 5.1. Example of configuration changes for the Simplified Routing feature for the value "none"
RiOS version | Default value | Configured value | Displayed value |
5.5 | none | none | (nothing) |
6.0 | dest-only | none | in-path simplified routing "none" |
Table 5.2. Example of configuration changes for the Simplified Routing feature for the value "dest-only"
RiOS version | Default value | Configured value | Displayed value |
5.5 | none | dest-only | in-path simplified routing "dest-only" |
6.0 | dest-only | dest-only | (nothing) |
Table 5.3. Example of configuration changes for the Simplified Routing feature for the value "all"
RiOS version | Default value | Configured value | Displayed value |
5.5 | none | all | in-path simplified routing "all" |
6.0 | dest-only | all | in-path simplified routing "all" |
An installation failure will be logged in the system logs:
Figure 5.51. Various upgrade failure scenarios
SH mgmtd[4229]: [mgmtd.WARNING]: Image install failed. -- The upgrade image provided is in \ compatible with the architecture of this appliance's hardware. Please provide an imag \ e for the x86_64 architecture.
The following failures are possible:
The upgrade image provided is incompatible with this appliance, which happens when a non-Steelhead image is being installed on the Steelhead appliance.
The upgrade image provided does not support this model or The upgrade image provided is incompatible with the architecture of this appliance's hardware. Please provide an image for the x86_64 architecture or The upgrade image provided is incompatible with the architecture of this appliance's hardware. Please provide an image for the i386 architecture, which happens when the provided upgrade image has the wrong CPU architecture, 32-bit instead of 64-bit or the other way around.
The upgrade image provided is too old. Please use a newer image. See log for more details, which happens when the upgrade image doesn't know about this model Steelhead appliance yet.
Unable to partition the disk to install image. Please retry, contact support if problem persists or Unable to create filesystem for upgrade image. Please retry, contact support if problem persists or Cannot find the image layout for machine. Please retry, contact support if problem persists or Partitions used to upgrade image are already mounted. Please unmount partitions manually before retrying or Could not get the upgrade image. Please check the url if using a remote image, which happens when there is a problem during the installation with one of the partitions on the Steelhead appliance.
The upgrade image provided does not pass validation. Please check
the to make sure the correct image is used for upgrade,
which happens when there is a problem with extracting the image. Use
the command
show images checksum
to compare the MD5 checksum of the upgrade image with the MD5
checksums found on the Riverbed Support website.
Error mounting tmpfs to upgrade image. Please contact support, which happens when the mounting of a installation partition fails.
No space left on disk to install image. Please contact support, which happens when the target installation partition is full.
If for a certain reason the upgrade was successful and the Steelhead appliance comes back but doesn't allow CLI or GUI access: This means that a back out of the upgrade cannot be performed.
The way out of this would be to hook up a serial console to the
Steelhead appliance and reboot the device. After the BIOS, the Grub
bootloader will show up with the text
Press any key to continue...
.
After pressing a key, the two boot partitions are displayed. Use
the
v
and the
^
to select the pre-upgrade boot image and press enter. After the
downgrade, access to the Steelhead appliance should be available
again and the Riverbed TAC should be involved to determine why after
the upgrade the connectivity failed.