Knowledge Collection: How to upgrade the firmware on an IBM WebSphere DataPower Appliance

Product documentation


Abstract

Instructions on how to successfully upgrade the firmware on an IBM WebSphere DataPower Appliance

Content

Follow these steps for a successful upgrade of your appliance.

  • - Step 1. Read this Important Information.
    1. Scope: This technote does not cover how to upgrade a DataPower appliance to add an optional feature. Please reference our technote on this topic.
    2. Plan: Create a firmware upgrade plan with all the stakeholders which includes a test plan to make sure the appliance works as expected after the upgrade.
      Review the release notes for the desired firmware and any intermediate major firmware releases for any new features or changes that may affect your environment.
      Release Notes: http://www.ibm.com/support/docview.wss?uid=swg21237631
    3. Critical planning information:
      • Critical Information: Please create a privileged user id as a back up for the "admin" account on your appliances. This will allow you to restore the "admin" account password in case the "admin" account is locked out or the password is lost.
      • Critical Fixes: Please read the list of critical updates documented by IBM Support in this flash: Critical updates for IBM WebSphere DataPower SOA appliances.
    V7 firmware information:
    Prerequisite firmware:
    If you are upgrading to V7 firmware, the appliances and Virtual Appliance must have a prerequisite firmware image installed first.
    • All M/T 7198 and 7199 appliances must be running 4.0.2.12, 5.0.0.0, or later.
    • All Virtual Appliances must be running 5.0.0.8 or later. For more information, see Supported Upgrade and Downgrade paths for DataPower Virtual Edition.
    • All M/T 4195 appliances must be running 4.0.1.17, 4.0.2.13, 5.0.0.8, or later
      Note:
      Contact support if issue with temporary space to upload the 7.0 image on a 4295 blade or virtual appliances.
    V6 firmware information:
      • Prerequisite firmware: If you are upgrading to V6 firmware, the appliances and Virtual Appliance must have a prerequisite firmware image installed first.
        • All M/T 9235 appliances must be running 3.8.2.18, 4.0.1.16, 4.0.2.12, 5.0.0.0, or later and does not support the 6.0.1.x firmware.
        • All M/T 7198 and 7199 appliances must be running 4.0.2.12, 5.0.0.0, or later.
        • All Virtual Appliances must be running 5.0.0.8 or later. For more information, see Supported Upgrade and Downgrade paths for DataPower Virtual Edition.
        • All M/T 4195 appliances must be running 4.0.1.17, 4.0.2.13, 5.0.0.8, or later.
      • Limitations
        • For M/T 7198 and 7199 appliances to upgrade from 4.0.1 to 6.0.0.0, you must first upgrade to 4.0.2.12 or 5.0.0 or later. This limitation will be removed in a future fix pack with APAR IC93188.
        • Upgrading using AMP, WAMT, WAMC might not work. This limitation will be removed in a future fix pack with APAR IC92167.
    V5 firmware information:
      • Prerequisite firmware: If you are upgrading to V5 firmware on a M/T 9235 and if the Machine Type 9235 appliance is running a firmware version earlier than 3.8.1.1, an upgrade directly to version 5.0 will fail. The appliance must be running firmware version 3.8.1.1 or later in order to upgrade to version 5.0. Upgrade the appliance firmware in two steps. First upgrade the appliance firmware to version 3.8.1.1 or later. Then upgrade from version 3.8.1.1 to version 5.0. This does not apply to the M/T 4195, 7199 or 7198.
      • New License Acceptance: After installing 5.0.0.x or later releases, customers will be required to explicitly accept the terms of the license agreements when updating the firmware. This affects all methods used to update the firmware (WebGUI, CLI, SOMA, & AMP). This includes when you have a 5.0.0.x fixpack installed and you wish to move to an earlier fix pack level.
      • Prevent SSL problems: If you are upgrading to from V3 firmware directly to V5 firmware see these two technotes to change your configuration prevent MQ SSL connection problems and other SSL connection problems.
    V4 firmware information:
      • Prevent SSL problems: If you are upgrading to V4 firmware see these two technotes to change your configuration prevent MQ SSL connection problems and other SSL connection problems.
      • Firmware 4.0.2 and the M/T 7993: Firmware 4.0.2 is not supported on the M/T 7993/9003. Support has ended for M/T 7993/9003.
      1. All Firmware information:
      • Supported and Recommended firmware levels: Review the list of recommended, generally available firmware for IBM WebSphere DataPower SOA Appliances in this document: Supported Firmware versions and recommended upgrade levels for IBM WebSphere DataPower SOA Appliances.
      • Release notes: Release notes are available for the major releases from the WebSphere DataPower Library page under Product Documentation. The appliance has firmware. The firmware is IBM Proprietary and IBM Confidential. The firmware is updated via one image to upgrade all features as purchased on the appliance.
      • XG45 DIM upgrade: If you purchase an license upgrade (DIM) for the XG45 after enabling the licenses you will need to reinstall the firmware to activate the new feature.
      2. Determining the firmware level for your unique business solution: IBM publishes several technotes to help your team determine the appropriate firmware levels for your business solution:


  • - Step 2. Identify The Firmware Image File Which Matches Your Appliance


    The DataPower firmware image file names have the following format or pattern:
    zzNNNN.
    licenses.scrypt{2/3/4}.

    If you are upgrading to firmware V6 or newer please see the "Determining firmware images to download" in the V6 information center.

    Otherwise, please follow the steps in this section of the technote.

    Using the information in this step you will resolve this pattern to the one image file name which matches your appliance, for example: xi3822.odbc.scrypt2. Fix Central has many image files for DataPower appliances; this will help you find the one file.

    The following steps will help you determine the firmware image file name which will work with your appliance.

    1. Determine the zz value in zzNNNN.licenses.scrypt{2/3/4}, which is the appliance model:
      1. You can use the DataPower WebGUI to obtain your appliance model. The DataPower model displays on the top left of the banner on every WebGUI page as XI50, XS40, XM70, XB60 XA35, XI52, XG45, or XB62.
      2. The first 2 characters of the model are the "zz" in the image format. Using this example throughout this section, for an XI50 model appliance, the image file name would start with XI: xiNNNN.licenses.scrypt{2/3/4}. Starting in version 5 of the firmware, the DataPower Blade firmware will start with xib for example: xibNNNN.licenses.scrypt2.
    2. The NNNN value in the firmware image file name is the firmware release level.
      1. To display the current firmware select Status, look under System and select Firmware Information, or scroll to the bottom of the WebGUI page. The firmware level and model are listed at the end of the selections.
      2. Read this technote to determine which firmware level you wish to install. Supported Firmware versions and recommended upgrade levels for IBM WebSphere DataPower SOA Appliances
      3. Next read the list of critical updates posted by IBM Support in this critical update flash to confirm your upgrade image choice has all critical updates included
      4. Firmware levels 4.0.1.0 - 4.0.1.3 are not available from IBM. Please upgrade to 4.0.1.4 or newer firmware levels.
      5. The firmware levels are listed in the form x.x.x.x, remove the '.', and this will be the "NNNN" in the firmware image. Using our example of xiNNNN.licenses.scrypt{2/3/4} , if you wish to install 3.8.2.3, NNNN would be 3823. This would be xi3823.licenses.scrypt{2/3} in our example. Note:
        1. An upgrade to firmware 4.0.1.0 or later requires the appliance to be currently running 3.7.3 or later. You will have to upgrade in 2 steps if your appliance is not running 3.7.3. First upgrade to a 3.7.3 fix pack then upgrade to a 4.0.1.0 fix pack.
        2. Are 68A the first characters in the appliance serial number? If so consult: What firmware version supports the Type 9235 Next Generation XML accelerator,
        3. Firmware 4.0.2 or newer is not supported on the M/T 7993/9003.
    3. Determine if you need a scrypt2, scrypt3, or scrypt4 file. The scrypt{2/3/4} value is based on the machine type. To display the hardware generation (machine type), select Administration > Device > System Settings. In the Product ID value, the machine type is the first 4 numbers, For example, 92354DX, is machine type or M/T 9235. Match the machine type or M/T:
      1. If the display shows "9235", or "4195", use scrypt of the form zzNNNN.licenses.scrypt2.
      2. If the display shows "7199" or "7198", use scrypt of the form zzNNNN.licenses.scrypt3. M/T 7199 and M/T 7198 use scrypt3 files and run V4 or newer firmware.
      3. If the display shows "5725", use scrypt of the form zzNNNN.licenses.scrypt4. M/T 5725 is for Virtual Appliances. All Virtual Appliances must be running 5.0.0.8 or later. For more information, see Supported Upgrade and Downgrade paths for DataPower Virtual Edition.
    4. Check the licenses you purchased on the appliance. This is the "licenses" value and you may have more than one license on the appliance.
      1. To display the license information select Status, look under System and select "Device Features". Note which features are enabled.
      2. Several licenses will appear. The licenses which affect your choice of image file name (depending on firmware level) are TAM, SQL/ODBC, and TIBCO. Make a note of which of these 4 licenses are displayed to use in the following steps, along with the machine type (M/T) and scrypt{2/3/4} you found. If you have other licenses, they will be updated as appropriate.
        1. If TAM, SQL/ODBC, and TIBCO do not appear, then zzNNNN.scrypt2/3/4 is the image file name pattern and you can proceed to step 5 "Here are examples....", to look at examples.
        2. XB appliances do not have ODBC in the image file name.
      3. M/T 9235 uses scrypt2. For firmware 3.8.1 or newer:
        1. If you see TAM, the image file name would contain "tam6" or "tam61" in "licenses" value. depending on your desired TAM level.
        2. If you see ODBC image file name would contain "odbc" in "licenses" value.
        3. If you see TIBCO, the image file name would contain "tibco" in "licenses" value.
      4. M/T 4195 uses scrypt2.
        1. For only firmware 3.8.1:
          1. If you see TAM, the image file name would contain "tam6" or "tam61" in "licenses" value. depending on your desired TAM level,
          2. If you see ODBC, the image file name would contain "odbc" in "licenses" value.
          3. If you see TIBCO, the image file name would contain "tibco" in "licenses" value.
        2. For firmware 3.8.2 or later:
          1. If you see TAM, the image file name would contain "tam6" or "tam61" in "licenses" value. depending on your desired TAM level,
          2. If you see ODBC, the image file name would contain "odbc" or "dco" in "licenses" value. See our DCO topic in our IBM Education Assistant website.
          3. If you see TIBCO, the image file name would contain "tibco" in "licenses" value.
        3. For firmware 5.0.0.0 or later:
          1. If you see TAM, the image file name would contain "tam6" or "tam61" in "licenses" value. depending on your desired TAM level,
          2. If you see ODBC, the image file name would contain "odbc" or "dco" in "licenses" value. See our DCO topic in our IBM Education Assistant website.
          3. If you see TIBCO, the image file name would contain "tibco" in "licenses" value.
          4. The image name will start with xib, instead of xi in previous firmware releases.
      5. M/T 7199 and M/T 7198 use scrypt3.
        1. For only firmware 4.0.1 with scrypt3:
          1. If you see TAM, the image file name would contain "tam6" or "tam61" in "licenses" value. depending on your desired TAM level,
          2. If you don't have a TAM license use "tam6"; TAM will not be installed on appliances which do not have this license.
          3. If you see ODBC, the image file name would contain "dco" in "licenses" value.
          4. If you see TIBCO, the image file name would contain "tibco" in "licenses" value
        2. For firmware 4.0.2.0 or later with scrypt3;
          1. If you see TAM, the image file name would contain "tam6" or "tam61" in "licenses" value. depending on your desired TAM level,
          2. If you don't have a TAM license use "tam6"; TAM will not be installed on appliances which do not have this license.
          3. If you see ODBC this is no longer included in the "licenses" value. DCO will automatically be installed on appliances which have this SQL/ODBC license.
          4. If you see TIBCO, the image file name would contain "tibco" in "licenses" value
    5. Here examples of completed firmware image file names:
      1. If you have an XI50 M/T 9235 with the ODBC license, and you wish to install 3.8.2.2 you will be searching to find an xi3822.odbc.scrypt2 image file name.
      2. If you have an XI52 M/T 7199 with ODBC and you wish to install 4.0.2.2, you will be searching to find an xi4022.tam6.scrypt3 image file name.

    With this information you can proceed to the next steps.


  • - Step 3. Download The Image Which Matches Your Appliance

    1. Go to the Fix Central web site
    2. A user id and password is now needed to access downloads on Fix Central. Here is our technote with more information.
    3. From the Product Group drop-down list, select WebSphere.
    4. From the Product drop-down list, select WebSphere DataPower SOA Appliances.
    5. For the Installed Version, choose 3.8.2 for example.
    6. Sign in with your IBM Account
    7. To limit the result to your WebSphere DataPower SOA Appliance model (XI50, XS40 etc.) Select the text radio button
    8. In the text file field, use XI to find all the XI50 , XS for all the XS40, files
    9. Select the firmware level
    10. After you select Agree you will see a list of all the firmware files for an XI50, (or XS40, etc.) or the files will be download. Using the information in step 2 you will have identified the one correct image file to use.
    11. Check the size of the file you downloaded. The file size should be close to the same size as on Fix Central. They will not be exact, but should be very close.

    If the image files appears as binary in your browser, please right-click and choose Save As from the browser,

    For help with accessing the Fix Central site, or suggestions to improve Fix Central, click on the feedback button on the Fix Central web page.



  • - Step 4. Install The Firmware Image.



    When possible use the WebGUI for firmware upgrades as the WebGUI is easier than issuing several CLI commands. WebGUI/CLI commands are provided for each step where the command exists for both methods.

    1. IMPORTANT: Check the firmware on the appliance.
      • From the WebGUI, under Status, look under System and select Firmware Information, or scroll to the bottom of the WebGUI page.
      • From the CLI issue the show version command.
    2. Check if this will downgrade the appliance to an older level of firmware than currently installed.
      If you need to downgrade to a different major release such as from 4.0.x.x to 3.8.3.x:. The only supported procedure is to use the the Resetting an IBM WebSphere DataPower SOA Appliance to install the 3.8.0.x image. A major release is identified by the first three points of the version such as: 3.7.3, 3.8.0, 3.8.1, and 3.8.2 which are all separate major releases.
    3. If you are installing V5 or V6 firmware, confirm you have the prerequisite firmware installed first. See "Step 1. Read this Important information" in this document.
    4. Back up the appliance's configuration in a safe location off the appliance. Reference our technote on backup and import features of the appliance.
    5. Confirm you have a working "admin" user ID.
    6. IMPORTANT: Create or confirm you have a back up privileged user id which can change the "admin" password if needed. See part 2 item 1 in our technote on lost passwords.
    7. Confirm the passwords for both user IDs have recently been changed and tested to ensure you can access the appliance with each user ID.
    8. IMPORTANT: Download and save to another computer any extra or unneeded files. You will want to delete the files from the appliance to make room for the upgrade.

      Freeing space and saving off unneeded files is important. When you upgrade the firmware the appliance creates a "roll back image" which includes the files (for example any logs you might be writing on the appliance), user ids, passwords, etc. This will take up file space on the appliance. The appliance manages file space and you cannot determine all the file space used by a roll back image or other files which the appliance maintains.
      1. Read our technote: DataPower File system explained for more information. You will want to delete the files off the appliance to make room for the upgrade. This will also reduce your "rollback (boot switch) image size", Firmware upgrade process creates a boot switch image in case you want to return to previous configuration, firmware, and user files. You should remove unneeded files prior to an upgrade, thus allowing for more space in future upgrades. The amount of file system space needed to upgrade depends on the history of the appliance and previous firmware upgrades.
      2. Using the WebGUI File management option or CLI commands, remove any unneeded files you might have added from the local, store, and LogStore directories. The WebGUI will be easier to use for this step:
        • In the WebGUI, click on Control panel and then click on the File Management icon. You can download and delete from the menu options. Click on Help for more information.
        • From the CLI, issue for each directory and each file to obtain output of the files:
          config
          dir local
          Review the output completely to determine what you can save then delete. See our technote on copying files to and from the appliance.
          After the files have been safely stored, remove the files from the appliance using the delete command. For example if you have a file called oldfile in the local directory, then delete local:\\\oldfile
      3. Check if you have enough space.
        • From the WebGUI select: "Status->Filesystem Information".
        • Use the CLI: "show filesystem" command
      4. If you are not able to free up enough space by backing up or deleting unneeded files, double check again. You will need a backup of the appliance stored on a computer or server before using these options:
        1. From the CLI issue these commands to remove the rollback image to free up more space.
          config
          flash
          boot delete
        2. You can delete domains, and then import the back-up zip after you have upgraded, via the WebGUI which provides options on what to import.
        3. You can "reinit" the appliance. See: Oure resetting an IBM WebSphere DataPower SOA Appliance technote. This will clear the appliance and upgrade the firmware image.
    9. Save the configuration.
      • In the WebGUI, use the “Save Config” option from the top pull down.
      • From the CLI: write mem
    10. IMPORTANT: Remove the appliance from the business solution or other environment, so that no traffic is flowing to the device and only the user who is performing the upgrade is logged on.
      1. Remove the appliance from load balancers or network environment to stop traffic from going to the appliance.
      2. Check that there is no traffic flowing on the interfaces.
        • In the WebGUI, select Status > IP-Network > Ethernet Interfaces
        • From the CLI:
          show int
          show int mode
      3. Disable the application domains
        • In the WebGUI:
          1. Using the WebGUI, look at the Control Panel, left hand navigation bar and expand Administration. Under Configuration section, Click on Application Domain.
          2. Note which domains are currently active.
          3. The default domain cannot be disabled; disable the other listed domains.
          4. Click on each domain, one at a time. Select the disable radio button, press Apply.
          5. After all domains are disabled, save the configuration.
        • From the CLI, note which domains are currently active and disable the domains.
          show domain
          conf domain
          <domainname>
          admin-state disabled
          After all domains are disabled, save the configuration using the write mem command.
    11. Reboot the appliance to free up resources.
      • In the WebGUI, from the Control Panel, choose System Control, then under Shutdown reboot the system by setting the mode to Reboot system. Click the Shutdown button, read the pop-up prompts and click the appropriate button. Be sure to wait if the pop-up message informs you to wait before taking any actions.
      • From the CLI. issue shutdown reboot
    12. Wait for the appliance to reboot.
    13. When the appliance reboots, completes, and you have access to the WebGUI, or CLI, upload the firmware image:
      • In the WebGUI: from the Control Panel, choose System Control. Next in the Boot Image section click Upload or Fetch to load the image file to the appliance.
      • From the CLI: use the best copy method to move the image file to the image directory. See our technote on copying files to and from the appliance.
    14. Make sure that the firmware image file is loaded and boot (install) the image:
      • In the WebGUI, in the Boot Image section pull down and install the new Firmware by clicking on Boot Image, Read the pop-up prompts and click the appropriate button. Be sure to wait if the pop-up message informs you to wait before taking any actions. Do not click on the Close button on the pop-up status notices. The status pop-up will change to a complete status, and you can then click OK.
      • From the CLI:
        config
        dir image
        if the image is found, then you can issue:
        flash
        boot image <image name>
    15. For firmware levels V5 or newer: After installing 5.0.0.x or later releases, you will be required to explicitly accept the terms of the license agreements when updating the firmware. (This affects all methods used to update the firmware (WebGUI, CLI, SOMA, & AMP)).
      • To accept the license using the WebGUI, do the following:
        1. Log in to the default domain.
        2. From the Control Panel, click the System Control icon.
        3. Navigate to the Boot Image area.
        4. From the Firmware File list, select the newly transferred firmware image.
        5. Select the I accept the terms of the license agreements check box.
        6. Click Boot Image and follow the prompts.
        7. Click Close to boot the appliance.
      • To accept the license from the command line, use the boot image command in the Flash configuration mode with the accept-license parameter:
        # configure terminal
        Global Configuration Mode
        config)# flash
        flash Configuration Mode
        (config-flash)# boot image accept-license <imagename> +....Firmware upgrade successful
        Device is rebooting now.
    16. Wait for the appliance to reboot and for the appliance to restart.
    17. Verify the firmware upgrade was successful:
      • In the WebGUI, scroll down to the bottom of the left hand navigation selections of the WebGUI.
      • From the CLI, use the show version command.
    18. Enable the desired application domains.
      • Using the WebGUI:
        1. Look at the Control Panel, left hand navigation bars. Expand Administration. Look For Configuration. Click on Application Domain under Configuration.
        2. Click on each domain, one at a time. Select the "enable" radio button, press Apply.
        3. After the desired domains are enabled, save the configuration.
      • Using the CLI enable each domain:
        show domain
        conf domain
        domainname
        admin-state enabled
    19. Add the appliance back to the business solution (add back to the load balancers or network environment).
    20. Test and verify the appliance operates correctly per your company's procedures.

    Note: If, for some reason, you need to go back to the previous firmware level and its configuration, you can toggle between releases by rolling back and forth between the current and the previous image. This includes rolling back between major releases.
    • In the WebGui:
      1. from the Control Panel, choose System Control.
      2. in the Firmware Roll-Back section click the "Firmware Roll-Back" button to toggle between images.
    • Using the CLI:
      1. Enter the command "CO".
      2. Enter the command "flash" press enter.
      3. Enter the command "boot switch" press enter.




  • - Resolution To Common Problems


    If the firmware did not upgrade or you have experienced problems after upgrading. Review this information.


    • A. Check the following first.
      1. IMPORTANT: After any failed upgrade attempts, reboot (shutdown reboot) the appliance.
      2. Check that you followed each step in the section "Step 4. Install The Firmware Image". Perform a reboot (shutdown reboot) and try all the steps again.
      3. When upgrading the firmware on an appliance, make sure you wait until the firmware upgrade completes before entering other commands. If you have an appliance with the HSM feature, each of the reboot portions of the upgrade steps can take 15 minutes to complete.
      4. If the upgrade is not working, check the throttle settings and turn them off temporarily while uploading the image file and upgrading the firmware in Objects -> System Settings-> Throttle Settings. Perform a shutdown reboot, then follow the steps in "Step 4. Install The Firmware Image".
      B. Memory and File space
      • Memory: In step 4, there are steps to make sure the appliance is not being used, no traffic, domains disabled, only the person doing the upgrade is logged on, and various times were a reboot is required. This will reduce memory usage.
      • File system space: In Step 4 there are suggestions on which directories to look at with all the stakeholders which use the appliance. There is a link to a technote on looking at file system use. With your team you can determine which files to store off the appliance or are no longer needed.
      • Flash drive space: On M/T 9235 appliances, the upgrade might fail with the error message "Loading firmware failed: Insufficient flash space available." The solution to this problem is to perform a 2-step upgrade. For more information, see Upgrade on M/T 9235 appliance fails with "Insufficient flash space available" error message.
      C. Did you receive an error message?
      1. "extracting firmware firmware parsing error":
        If you see a message indicating " extracting firmware firmware parsing error": Download the image file again. The file size should be close to the same size as on Fix Central. They will not be exact, but should be very close. Perform a shutdown reboot, then follow the steps in "Step 4. Install The Firmware Image".
      2. "Error while processing Action ... Validate boot image failed "Validation Failed":
        If you see this message, the image file might not have downloaded completely from Fix Central. Download a new copy of the file. The file size should be close to the same size as on Fix Central. Perform a shutdown reboot, then follow the steps in "Step 4. Install The Firmware Image".
      3. Warnings have been detected: Would you like to continue? Firmware does not contain supported feature '_____':
        This message indicates that the firmware image is not a match to the appliance. See section 2 "Step 2. Identify The Firmware Image File Which Matches Your Appliance". Download a matching image. Perform a shutdown reboot, then follow the steps in "Step 4. Install The Firmware Image".
      4. Upgrade failure in dynamic loader: Preserve user modified data failed The dynamic loader failed to upgrade the system (-1):
        If the upgrade did not work and you see this message, the resident loader will be used instead. Confirm that the firmware upgrade was successful by checking the appliance firmware level via the WebGUI or "show version" CLI command. This message is informational.
      5. Upgrade failure in dynamic loader: Switch active firmware failed The dynamic loader failed to upgrade the system (-1):
        If you see this message after upgrading, the resident loader will be used instead ...": Confirm that the firmware upgrade was successful by checking the appliance firmware level via the WebGUI or "show version" CLI command. This message is informational.
      6. Loading firmware failed: Preserve user modified data failed: Insufficient flash space available Could not install firmware image. The system will not reboot. ",
        There is not enough space available to upgrade the appliance. Follow the steps in "Step 4. Install the Firmware Image" which describe how to save files and free up space. Additional symptom: Preserve user modified data failed
      7. Wed Oct 15 2008 22:27:01 [crypto][error] certificate( yourcertname): tid(123): certificate 'pubcert:///yourcertname.pem' is expired":
        See this technote: Startup error similar to "'pubcert:///XYZ-Class-1-CA-.pem' is expired" noticed during monitoring or upgrading.
      8. % Loading firmware failed: Internal receive API error (3)
        The API error (3) is due to a time-out. The time-out happens when copying files for the rollback feature, when there is a large number of files to process. When the device reboots, the upgrade will continue and should be successful. Use the WebGUI or the CLI commands " show version" and "show license" to confirm upgrade was complete. If the upgrade is not successful, you might need more space. Perform a shutdown reboot, then follow the steps in "Step 4. Install The Firmware Image".
      9. % Loading firmware failed: Extract firmware failed: Archive extraction
        There is not enough space available to upgrade the appliance. Follow the steps in "Step 4. Install the Firmware Image" which describe how to save files and free up space.
      D. Objects not showing after an upgrade?
      1. Ethernet Ports do not show:
        After firmware downgrade, Ethernet ports are not showing on the appliance. Review our What firmware version supports the Type 9235 Next Generation XML accelerator technote. Some appliances require a higher level of firmware. Upgrade to the 3.7.3.7 or newer fix pack image. Run the "show version" and "show license", "show int" and "show int mode" CLI commands to check if all the Ethernet ports reappear.
      2. Domains do not show:
        If after upgrading the firmware, the domains you have configured do not appear: From the WebGUI create each domain with the same name again. The domains and services previously configured should now appear. Otherwise follow these steps to contact IBM WebSphere DataPower SOA Appliance Support.
      3. Folders and files:
        Unable to access the folders/files on particular domain after upgrading firmware:
        While upgrading DataPower firmware, you might notice that the following message does not show up on a particular domain in an error report.
        For example, on the "yourTestDomainName" domain:
        [yourTestDomainName][mgmt][info] raid-volume(raid0): trans(12345): Installed storage volume access link logstore://ondisk
        This missing ondisk subdirectory is caused by an asynchronous issue due to a race condition during boot time. A work around method is to issue the 'shutdown reboot' command. The hard disk folders/files should be available after the appliance restarts.
      E. Connection problems after upgrade:
      1. SSL connection errors after upgrade to firmware V4. If you are upgrading to V4 firmware see these two technotes to change your change your configuration: prevent MQ SSL connection problems and SSL connection problems. Examples of connection errors are: http error 0x80e00130 or "SSL client refused to connect to an insecure SSL Server"
      2. Unable to connect using WebGUI or ssh after upgrading firmware:
        This can occur if you are using a custom cert or authentication for the management services, if any of the associated certs have expired. Expired certs are removed at upgrade time.
        The first step is to verify that the network is functioning correctly using these commands:
        show int
        show int mode
        show route

        These commands will show if there is any network activity as well as the connection details such as link speed. Once the network is confirmed the quickest way to recover the web management (WebGUI) and ssh services is to delete them and recreate them with the default settings using the serial console. These commands will reset the RBM's, ACL's, WebGUI and ssh services all to the default settings. Note: If the ssh is working you may omit any commands containing ssh.

        config
        web-mgmt
        no ssl
        exit
        write mem
        y
        no web-mgmt
        no ssh
        rbm
        reset
        exit
        acl web-mgmt
        reset
        exit
        acl ssh
        reset
        exit
        write mem
        (key step to remove the current settings)
        y
        web-mgmt
        <ip to listen on or 0.0.0.0 for all> <port to use default is 9090>
        ssh <ip to listen on or 0.0.0.0 for all> <port to use default is 22>
        write mem
        y

        Once complete, test the service and confirm you can now access the appliance. Then you may work to configure any custom certs or authentication settings desired.
      F. Other problems during upgrade:
      1. IC63703 The auto.config file and the startup.config file can get out of sync during firmware upgrades. Ensure these files are linked after the upgrade is done: Login to the default domain in the CLI and execute the following:
        config
        save-config overwrite
        write memory
      2. If you are following all the steps in this technote using the WebGUI and the upgrade is still not successful, reboot the appliance, then upload the image via the WebGUI, and use the following CLI commands to upgrade the firmware. (Note: When uploading the firmware image you may rename it to make typing it into the CLI command easier.) If the upgrade fails, save any messages from this session to assist in troubleshooting the upgrade issue.
        config
        flash
        boot image
        <image name>



  • - Considerations when using scripts or programs

    1. If you are using scripts or programs to upgrade the appliance firmware, the programs should be designed to follow the same steps a person would perform to prepare the appliance for an upgrade. See Step 4 in this technote.
    2. See Step 4 for information on prerequisite firmware or other upgrade actions.
    3. See this technote: SSL connection to XML Management Interface (SOMA, AMP, WS-Management, and WSDM) or WebGUI might fail. DataPower appliances started using a new Root CA certificate with M/T 7199 and 7198 (appliances that were first available with DataPower firmware version 4.0.1). Starting with DataPower 5.0.0, the M/T 9235 and 4195 appliances start using the new Root CA certificate that has always been used by the M/T 7199 and 7198 appliances. This means that customers with M/T 9235 and 4195 appliances who have been using the old DataPower root CA certificate in their trust store will start having SSL connection failures when they upgrade to 5.0.0. Follow the instruction in the technote above.
    4. If you are upgrading to V5 or newer firmware:
      After V5 you will be required to explicitly accept the terms of the license agreements when updating the firmware and when you downgrade an appliance from a 5.0.0.x fix pack to an older fix pack level. This affects all methods used to update the firmware (WebGUI, CLI, SOMA, & AMP).
        1. To use your existing scripts without changes, place an empty file named "license.accepted" in the temporary directory ( temporary://license.accepted) before running the current upgrade scripts. Note: This is a temporary file and will not be persisted after a reboot. Therefore it will be needed prior to any upgrade after the 5.0.0.x firmware is installed.
        2. Otherwise:
          1. If using SOMA, use the <ApplyPatch> element containing the <AcceptLicense/> element.
          2. If using AMP, use the following element containing the <dp:AcceptLicense/> element:<dp:SetFirmwareRequest xmlns:dp="http://www.datapower.com/schemas/appliance/management/2.0">



Original publication date

2012/6/2

Rate this page:

(0 users)Average rating

Document information


More support for:

IBM DataPower Gateways
General

Software version:

4.0.2, 5.0.0, 6.0.0, 6.0.1, 7.0.0

Operating system(s):

Firmware

Software edition:

Edition Independent

Reference #:

7015333

Modified date:

2012-06-29

Translate my page

Machine Translation

Content navigation