5.9. Downgrade and upgrade issues

The upgrade and downgrade process on Steelhead appliances is not always straightforward. The following restrictions and caveats are in place:

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.

5.9.1. Upgrade via the CLI

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

5.9.2. Force a downgrade

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.

5.9.3. New features after an upgrade

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 versionDefault valueConfigured valueDisplayed value
5.5nonenone(nothing)
6.0dest-onlynonein-path simplified routing "none"

Table 5.2. Example of configuration changes for the Simplified Routing feature for the value "dest-only"

RiOS versionDefault valueConfigured valueDisplayed value
5.5nonedest-onlyin-path simplified routing "dest-only"
6.0dest-onlydest-only(nothing)

Table 5.3. Example of configuration changes for the Simplified Routing feature for the value "all"

RiOS versionDefault valueConfigured valueDisplayed value
5.5noneallin-path simplified routing "all"
6.0dest-onlyallin-path simplified routing "all"

5.9.4. Failures during the installation phase

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.

5.9.5. Upgrade failed, CLI doesn't become available anymore

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.