Backing up, exporting and importing the configuration of an IBM WebSphere DataPower SOA Appliance or Virtual Edition.

Technote (FAQ)


Question

The following information describes backing up, exporting, and importing IBM WebSphere DataPower appliance or Virtual Edition configurations.

Answer


Table Of Contents

PART 1: Considerations for backup or export of an appliance configuration and importing the configuration
PART 2: Backing up and exporting the appliance configuration
PART 3: Importing the backup configuration to the new appliance
PART 4: Secure backup


Part 1: Considerations for backup and import of an appliance configuration



1. Importing a configuration from a higher major release of firmware to a lower firmware release is not supported.

    If you create a configuration on an appliance running a higher major release of the firmware, the configuration could not be exported from that appliance and then imported to an appliance running a lower major release of firmware. For example a configuration created on 3.8.0.x could not be imported to an appliance running 3.7.3.x.

    When the configuration from an appliance running an earlier major release of the firmware is exported and then imported to an appliance running a newer major release of the firmware, if the configuration is not changed in any manner, the configuration can be exported and then imported back to that appliance with the earlier major release level of firmware.

    If the configuration from an appliance running an earlier firmware level is imported to an appliance running a newer firmware image and is changed in any way, the configuration cannot be exported and then imported to an appliance running an earlier level of firmware.

    Note: The best practice is to only use exports created on one major release with appliances running that release or higher. If a configuration is used across environments running multiple major releases of the firmware any changes made to the configuration on the higher major release will need to be manually added to the lower major release.

    You can import a configuration from a XS40 to a XI50, but can not import an XI50 configuration to a XS40.

    Refer to the Administrators Guide under the "Backing up and exporting configuration data" topic. The Administrators Guide and information centers are available from this site.

2. Changing the exported configuration files is not supported.
    If the configuration export is modified, the import of the modified configuration file is not supported and could have unpredictable results. Use the appliance's WebGui to make any changes then export the configuration. Use DataPower features such as host alias when you need to import and export to different appliances. To help manage appliance specific configuration see the Administrators Guide and information centers available from this site for more information.
3. Make sure the user id has the authority to backup the appliance.
    Not all users have authority to backup the appliance or all domains. Consult the Administrators Guide and information centers available from this site.
4. Determine if the RAID should be part of the secure backup.

    Check the files located on the appliance RAID to determine if these appliances should be part of the secure backup or saved using other options. Backup of the RAID will require more space and processing on the appliance. Saving the RAID in a secure backup might not be the best choice in all scenarios. Reference our filesystem technote and consult the Administrators Guide and information centers available from this site.



Part 2: Backing up the appliance configuration (not secure back-up).



Refer to the Administrators Guide under the "Backing up and exporting configuration data" topic. The Administrators Guide is available from this site

Use the following procedure to backup all exportable configuration data for your appliance. If you are not logged on with the 'admin' id, only the subset of the appliance configuration that available for you to backup.

  1. Before taking a backup of the appliance, remove the appliance from the business solution, development or test environment. You want to obtain good backup of the appliance. Make sure there are no changes in progress. Make sure no traffic is flowing though the appliance, In the WebGui, select Status > IP-Network > Ethernet Interfaces
  2. Using the WebGUI File management option or CLI commands , remove any unneeded files you may have added from the local, store, and logstore directories.
    1. In the WebGui, click on Control panel and then click on the File Management icon.
    2. Review the output completely to determine what you can save then delete. See our technote on copying files to and from the appliance.
    3. You can download and delete from the menu options. Click on Help for more information.
    4. After the files have been safely stored, remove the files from the appliance.
  3. Select Administration > Configuration > Export Configuration. This will display the Initial Export Configuration screen
  4. Select Create a backup of the entire system, and click Next to display the file name screen.
  5. You should provide a meaningful description of the appliance configuration you are exporting in the comment field. This will help to identify the backup at a later date.
  6. Specify a file name for the export file that will be created in the export: directory. The default file type is *.zip. If a file with the specified name already exists, it will be overwritten.
  7. Click Next. The exportable appliance configuration will be written to the specified file (in the export: directory). Copy this file to a safe (off-appliance) location. You may wish to perform the copy using the Download button, which will copy it to your browser client machine during the backup processing via the WebGUI. After the file is saved (off-appliance) you can consider deleting the file.
  8. Click Done.

The export file you created above contains the complete configuration of your original appliance, with the exception of the following types of objects:
  • User Account objects
  • Certificate objects
  • Key objects (Only HSM equipped appliances)
  • Web Service Proxy with XML Injection file

Note:
If your application uses the Web Services proxy with an XML Injection pattern file, this file will not be included in the exported configuration (although the reference to the file will be included). Such pattern files must therefore be copied of the appliance manually then re-loaded.

Once you have loaded your exported configuration into the other appliance, you will need to re-create user accounts on the new appliance, and reload any certificates and keys. Before continuing, make sure that you have all the necessary information to manually recreate the above objects.

Listing user accounts.

Using the WebGUI, logged in with the "admin" account, choose Administration > Access > Manage User Accounts. This will display the Configure User Account page, which lists all the user accounts currently defined in the appliance. Choose each account in turn, clicking on the account name to display the details page for that account. Record account name, the admin state setting, the comment, the access level and any information on the SNMP V3 User Credentials tab.

Exporting or Listing keys

If your appliance is configured with an HSM, then keys may be exported, provided they were flagged as exportable when created. The procedure to export keys from an HSM is described in the Hardware Security Module Guide, chapter 20, "Exporting Keys and Certificates", and will not be repeated here.

If your appliance does not have an HSM, or some of your keys are not marked as exportable, then the key(s) must be recreated in the new appliance. Keys that were originally generated on the appliance can be replaced by freshly-generated keys on the new appliance, and corresponding certificates should be replaced with new ones. The process for doing this is highly application-specific and will not be described further here. Keys that were imported from an external source should be re-imported in the new appliance. The process for doing this is described below, under "Rebuilding key objects".

Keys contained within the appliance are listed on the Objects > Crypto Configuration > Crypto Key page.







Part 3. Importing the backup configuration to the new appliance (a non-secure backup)



This process is described in the DataPower Administrators Guide, Chapter 13 ("Managing the configuration of the appliance") in the section entitled "Importing configuration data". The following is a brief description of the process. The Administrators Guide is the authoritative source for this information.


  1. Before importing an appliance configuration, remove the appliance from the business solution, development or test environment. Make sure there are no changes in progress. Make sure no traffic is flowing though the appliance, In the WebGui, select Status > IP-Network > Ethernet Interfaces
  2. Using the WebGUI on the new appliance, log in under the admin account. You should ensure that the backup configuration file you created above resides on your browser client machine.
  3. Select Administration > Configuration > Import Configuration to display the Import Configuration window.
  4. Use the radio buttons to select a ZIP bundle (as created in the step above).
  5. Click Browse to select the file to import. Choose the file containing your configuration backup.
  6. Ensure that Rewrite Local Service Addresses is set to On. This will set the appliance to use the IP addresses defined in the configuration you are importing, rather than whatever IP address it currently has. This way, the new appliance will use the same IP addresses as the original appliance.
  7. Click Next to show the list of domains to import. Select All.
  8. Click Next to display the Import Object Selection List window. Select All.
  9. Click Next to display the Import Summary window. Click All, then Import to initiate file transfer. When this process is complete, the WebGUI will display the Object Import Results window.
  10. Click Done to close this window.
  11. Consider if you should delete the backup file from the appliance.

Rebuilding the non-exportable objects

As described above, certain objects cannot be backed up from the original appliance. Therefore these objects must be recreated in the new appliance manually.

Rebuilding certificate objects.

Certificates downloaded from the old appliance as described above in the section titled "Listing certificate objects" may be installed in the new appliance on the Objects > Crypto Configurations > Crypto Certificate page. Press the " Add" button to bring up the Configure Crypto Certificate window. Use the same name for the certificate object as on the original appliance, and use the " Upload" button to upload the corresponding certificate file.

Rebuilding key objects.

Each key identified by the process above must be either re-imported or re-generated within the new appliance. For keys being re-generated, the process is application-specific, and will not be described here.

Keys that were exported from the original appliance can be re-imported on the new appliance using the Administration > Miscellaneous > Crypto Tools > Import Crypto Object tab, as described in the Administrators Guide, chapter 7, "Securing Communication".

Keys that are in external (non-DataPower) files are imported via the Objects > Crypto Configuration > Crypto Key page, pressing the Add button for each key to be imported from an external file.

Completely test the appliance before introducing the appliance back in to the production, development, test, or other environment.

If the backup is not successful:
  • Double check the appliance is not in use, and all steps were followed.
  • Double check the user's authority level.
  • Look for messages in the DataPower logs.
  • The complete backup or restore might fail if there are lots of domains. One symptom is you are not able to access the WebGui after a backup. It is usually possible to backup or restore domains which are smaller increments to work around the current limitations.
  • Internal space might not be released if a backup fails or if the "Done" button is not clicked after a successful backup. You can determine that the space has not been released by doing a "show filesystem" command from the CLI before the backup starts, another "show filesystem" while the backup is taking place, and a final "show filesystem" after the backup has ended. If the Free Internal Space does not go up to pre-backup levels after the backup has ended and the Free Internal Space stays at the lower level for 15 minutes after the backup has ended, it is likely that you have this problem. If you encounter this problem, you can regain the lost Free Internal Space by shutting down and restarting the DataPower appliance.



Part 4: Secure Backup and import of a Secure back up ( disaster recovery)



A secure backup feature to help manage disaster recovery was introduced in 3.8.1. You can learn about this feature in our Infomation Centers on our from our library page. Searching on "managing disaster recovery yyy" where yyy is your appliance model in the information center. For example "managing disaster recovery xi50" The Administrators Guide and information centers are available

On a DataPower appliance, disaster recovery is the ability to create a secure backup that you can use to recover the complete configuration of a lost appliance. Disaster recovery uses a backup-restore process.

If you are planing to preform a secure restore on an appliance the appliance needs the previous configuration removed. See our technote on Resetting an IBM WebSphereDataPower SOA Appliance to initial factory settings

Note:
Disaster recovery is available only if you enabled disaster recovery mode during the initial firmware setup of the appliance. If not enabled, you must reinitialize the appliance with the reinitialize command and enable disaster recovery. To determine if disaster recovery is available, click Administration > Device > System Settings. If the Backup Mode property is set to Secure, disaster recovery is available.
Additional information on this topic:


Creating a secure back up image
  1. Before taking a backup of the appliance, remove the appliance from the business solution, development or test environment. You want to obtain good backup of the appliance. Make sure there are no changes in progress. Make sure no traffic is flowing though the appliance, In the WebGui, select Status > IP-Network > Ethernet Interfaces
  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.
  3. In the WebGui, click on Control panel and then click on the File Management icon.
  4. Review the output completely to determine what you can save then delete. See our technote on copying files to and from the appliance.
  5. You can download and delete from the menu options. Click on Help for more information.
  6. After the files have been safely stored, remove the files from the appliance.
  7. Select Administration > Configuration > Export Configuration. This will display the Initial Export Configuration screen
  8. Select Create a backup of the entire system, and click Next to display the file name screen.
  9. You should provide a meaningful description of the appliance configuration you are exporting in the comment field. This will help to identify the backup at a later date.
  10. Specify a file name for the export file that will be created in the export: directory. The default file type is *.zip. If a file with the specified name already exists, it will be overwritten.
  11. Click Next. The exportable appliance configuration will be written to the specified file (in the export: directory). Copy this file to a safe (off-appliance) location. You may wish to perform the copy using the Download button, which will copy it to your browser client machine during the backup processing via the WebGUI. After the file is saved (off-appliance) you can consider deleting the file.
  12. Click Done.

Installing a secure back up image.
  1. Before importing an appliance configuration, remove the appliance from the business solution, development or test environment. Make sure there are no changes in progress. Make sure no traffic is flowing though the appliance, In the WebGui, select Status > IP-Network > Ethernet Interfaces
  2. Make sure the appliance is at the initial factory settings, See our technote on Resetting an IBM WebSphereDataPower SOA Appliance to initial factory settings
  3. Configure the basic configuration to allow access to the webgui. This will be replaced when the secure backup completes.
  4. Using the WebGUI on the new appliance, log in under the admin account. You should ensure that the backup configuration file you created above resides on your browser client machine.
  5. Select Administration > Configuration > Import Configuration to display the Import Configuration window.
  6. Use the radio buttons to select a ZIP bundle (as created in the step above).
  7. Click Browse to select the file to import. Choose the file containing your configuration backup.
  8. Ensure that Rewrite Local Service Addresses is set to On. This will set the appliance to use the IP addresses defined in the configuration you are importing, rather than whatever IP address it currently has. This way, the new appliance will use the same IP addresses as the original appliance.
  9. Click Next to show the list of domains to import. Select All.
  10. Click Next to display the Import Object Selection List window. Select All.
  11. Click Next to display the Import Summary window. Click All, then Import to initiate file transfer. When this process is complete, the WebGUI will display the Object Import Results window.
  12. Click Done to close this window.
  13. Consider if you should delete the backup file from the appliance.

Additional References:

Secure backup-restore for WebSphere DataPower SOA Appliances
http://www.ibm.com/developerworks/websphere/library/techarticles/1009_furbee/1009_furbee.html

Backing up, exporting and importing the configuration of an IBM WebSphere DataPower SOA Appliance.
http://www-01.ibm.com/support/docview.wss?uid=swg21416135

Authentication failure using the DataPower WebGUI to copy large files
http://www-01.ibm.com/support/docview.wss?uid=swg21512170

IC86960: APPLIANCE MIGHT RESTART WHILE TRANSFERRING VERY BIG FILES VIA WEBGUI
http://www-01.ibm.com/support/docview.wss?uid=swg1IC86960

DataPower Secure Backup to an SFTP destination
http://www-01.ibm.com/support/docview.wss?uid=swg21507543


Cross reference information
Segment Product Component Platform Version Edition
Business Integration WebSphere DataPower Low Latency Appliance XM70 Not Applicable
Business Integration WebSphere DataPower SOA Appliances Not Applicable
Business Integration WebSphere DataPower XML Accelerator XA35 Not Applicable
Business Integration WebSphere DataPower XML Security Gateway XS40 Not Applicable

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

WebSphere DataPower Integration Appliance XI50

Software version:

3.8.2, 4.0.1, 4.0.2, 5.0.0, 6.0.0, 6.0.0.1

Operating system(s):

Firmware

Reference #:

1416135

Modified date:

2011-03-30

Translate my page

Machine Translation

Content navigation