Migrating your configuration from an IBM DataPower Gateway appliance to a different appliance

Overview

The recommended process for moving your configuration from an IBM DataPower Gateway appliance to a new or replacement appliance without using secure backup

Preparation - Hardware

.

• Cabling and connectivity - See this technote for details on connecting to the serial console.

All technical specifications and additional information for the appliance models can be found in the Knowledge Center


Preparation - Software Environment

Prior to attempting the migration, verify that all external software (e.g. TAM) is at a version that is supported by the target WebSphere DataPower SOA firmware release.

Upgrading the firmware on the 7993/9002

The upgrade process is documented in chapter 14 of the WebGUI guide, "Managing the Firmware Image". The 7993/9002 hardware contains a limited amount of flash memory; it is possible that an upgrade will fail on systems with large customer configurations due to insufficient flash space.

After performing the firmware upgrade, and after the appliance has rebooted, connect to the console and issue the write mem command, and then reboot the appliance a second time.

Once the firmware has been upgraded, do not make any changes except those found necessary to restore functionality to the customer application. Do not attempt to make use of new firmware features at this stage - such enhancements to the customer application should be left until after the application has been successfully migrated and tested on the 9235.

Testing the customer configuration

After the 7993/9002 appliance has been upgraded to the same firmware release as the target 9235/9004 appliance, the customer application should be well tested to identify any issues that have appeared due to differences between WebSphere DataPower firmware revisions. In general, IBM strives to preserve behavior of customer configurations across an upgrade; however there are some issues that have been identified and these are listed here.

• The DataPower plugin for XMLspy is no longer supported.
• If you run a CLI script that deletes multiple configuration objects, be aware that object deletion is an asynchronous process, and this may result in attempts to delete child objects failing, if attempted soon after the parent object has apparently been deleted. Timing of such operations may change as a result of the upgrade, which may mean that deletion scripts that previously worked now run into this problem.

• If using the import-package command to import a package to be saved as part of the running configuration of the appliance, the auto-execute off sub-command must be specified.

Migrating the tested configuration to the 9235

To migrate your configuration to the new hardware, you must create a backup of your configuration on your current appliance, import this configuration into the new appliance, and then manually recreate all non-exportable configuration objects.

Backing up your current configuration on the original appliance

This process is described in the DataPower WebGUI Guide, Chapter 17 ("Managing the appliance configuration") in the section entitled "Backing up and exporting configuration data", subsection "Backing up the entire appliance". The following is a brief description of the process; the WebGUI Guide is the authoritative source for this information.

Use the following procedure to backup all exportable configuration data for your original appliance. Only the subset of the appliance configuration that is visible to the account you are logged in to will be exported, so first ensure that you are logged into the WebGUI as admin.

• Select ADMINISTRATION > Configuration > Export Configuration. This will display the Initial Export Configuration screen
• Select Create a backup of the entire system, and click Next to display the file name screen.
• 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.
• 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.
• Click Next. The exportable appliance configuration will be written to the specified file (in the export: directory). Copy this file to a safe (off-box) location. When you import the configuration into the new appliance, this file should reside on your client system, so you may wish to perform the copy using the Download button, which will copy it to your browser client machine.
• Click Done.

The export file you created above contains the complete configuration of your original appliance, with the exception of the following types of object:

• User Account objects
• Certificate objects
• Key objects
• Password maps.

In addition, if your application uses the Web Services proxy with an XML Injection pattern file, the file itself will not be included in the exported configuration (although the reference to the file will be). Such pattern files must therefore be copied from the 7993/9002 and manually re-loaded into the 9235/9004.

Once you have loaded your exported configuration into the new appliance, you will need to re-create user accounts on the new appliance, reload any certificates and keys, and rebuild any password maps your current appliance uses. 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 under 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.

Listing certificates.

Although certificates are not exported as part of a configuration backup, they can be manually exported. To see a list of the defined certificates in the WebGUI select Objects > Crypto Configuration > Crypto Certificate. For each certificate in the list in turn, click on its name to open up the Configure Crypto Certificate window. Click on the "Export" link near the top right of the page. This will export the certificate to a file on your client system. Choose a meaningful filename to save the certificate in (the same as the certificate object name, if possible), and download it. Record the certificate name, the admin state setting, and the Ignore Expiration Dates radio buttons.

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 WebGUI 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.

Listing password map entries

The password map is only available via the console; there is currently no WebGUI support for it. To display the password map entries, connect to the console, either via the appliance serial port, or using telnet, and issue the command: show password-map. This will list the password aliases that are defined. For each alias, the corresponding plaintext password must be determined from record; plain text passwords cannot be extracted from the appliance.

Importing the backup configuration to the new appliance.

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

• 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.
• Select ADMINISTRATION > Configuration > Import Configuration to display the Import Configuration window.
• Use the radio buttons to select a ZIP bundle (as created in the step above).
• Click Browse to select the file to import. Choose the file containing your configuration backup.
• 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.
• Click Next to show the list of domains to import. Select All.
• Click Next to display the Import Object Selection List window. Select All.
• 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.
• Click Done to close this window.

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 WebGUI Guide, chapter 20, "Importing Keys and Certificates".

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.

Rebuilding password maps.

If your old appliance used a password map, this must be recreated on the new appliance. This procedure must be performed via the console; password maps are not currently supported via the WebGUI.

Having connected to the console, issue the password-map command to create a password map and allow entries to be input. For each password-alias discovered above, enter the plaintext password and the alias. Enter a blank alias to terminate the input.