The following information describes backing up, exporting, and importing IBM WebSphere DataPower appliance configurations.
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.
Not all users have authority to backup the appliance or all domains. Consult the
Administrators Guide and information centers available
from this site.
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. Consult the Administrators Guide and information centers available from this site.
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.
- 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. You can use the "show int" and "show int mode" to check traffic. You can use show cpu to check that the appliance is not in use.
- 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-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.
- 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
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.
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.
- Before importing an appliance configuration, remove the appliance from the business solution, development or test environment. You can use the show int and show int mode to check traffic. You can use show cpu to check that the appliance is not in use.
- 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 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.
A secure backup feature to help manage disaster recovery was introduced in 3.8.1. You can learn about this feature in our 3.8.1 Information Center. by searching on "managing disaster recovery yyy" where yyy is your appliance model. For example "managing disaster recovery xi50" The Administrators Guide and information centers are available from this site for other releases.
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.
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:
|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|