Secure backup-restore for WebSphere DataPower SOA Appliances

This article describes the secure backup-restore function for WebSphere DataPower SOA Appliances (first available in 3.8.1), including device preparation and detailed implementation steps. With DataPower secure backup-restore, you can perform a full-box backup of a DataPower device configuration, and then restore the image to a compatible device. Benefits of secure backup-restore include disaster recovery, workarounds for device problems, and copying a configuration from one device to other devices in the same environment. Backup files are encrypted, and can either be stored locally or saved to an FTP location.

Joseph E. Furbee (jefurbee@us.ibm.com), Software Test Specialist, IBM Software Services for WebSphere, IBM

Photo of Joe FurbeeJoe Furbee is a Software Test Specialist with IBM Software Services for WebSphere. He has testing experience with WebSphere middleware, SOA implementations, CRM Siebel, and education software. While working on WebSphere DataPower SOA Appliances, he has been involved in multi-box management, zSystem enterprise integration, and special customer issues.



30 May 2012 (First published 15 September 2010)

Also available in Spanish

Introduction

The disaster recovery functions secure-backup and secure-restore in IBM® WebSphere® DataPower® SOA Appliances enable administrators to create a backup of a DataPower appliance and restore it to a compatible appliance (a compatible appliance is one with identical firmware level and storage capacity). The main purpose of secure backup-restore is disaster recovery, but you can also use it to take the configuration from one appliance and replicate it. The backup files are encrypted, so they can either be stored locally or saved to an FTP location. Unlike a standard backup, a secure backup contains certificates, keys and user passwords; which are not included in a standard backup. This article describes the backup and restore processes and includes some technical details on the data encryption. For information on best practices and considerations after performing a restore, see Secure restore for WebSphere DataPower SOA Appliances.

Why use secure backup-restore?

Secure-backup creates a set of files that you can use with a secure-restore for multiple purposes:

  • Assure appliance recovery.
  • At end of life of an appliance, move the configuration to a replacement appliance.
  • Use the backup from one appliance to configure multiple, similar function, compatible appliances.
  • Use during the development cycle to move configurations from a development appliance to test, to pre-production, and finally to production.

Disaster recovery mode

DataPower Disaster Recovery mode (identified by Secure mode in system settings) is selected only at installation time and enables an administrator to make a backup of the appliance. When not in Disaster Recovery mode (Normal mode in system settings), the appliance cannot export private keys. When Disaster Recovery mode is selected, the appliance can encrypt the keys and other data. Once the Disaster Recovery mode is set, you cannot change it without reinitializing the appliance. However, if an appliance in Normal mode is restored, the restore will proceed and will permanently change the appliance to Secure mode during the process.

Secure-backup

The secure-backup function lets administrators copy private data from a DataPower appliance. You can use the backup file in a variety of ways, including disaster recovery, appliance end-of-life process, or replicating appliance settings to other appliances.

Secure-backup basics

To use the secure-backup command, the appliance must be set to Disaster Recovery mode at installation time. The backup can be saved locally on the appliance in the local: or temporary: directories, or you can save it remotely using FTP. The command requires a public certificate for encrypting the backup data. To restore the backup files, the private key associated with the public certificate is required.

The backup is a collection of compressed, encrypted files along with a manifest, which is signed to ensure data integrity, and describes the appliance firmware level, backup date, appliance settings, and certificate used for encryption, and includes a list of the encrypted files with their size and checksum. Excluding firmware files enables the backup to be as small as possible but requires that at restore time, the appliance must match the firmware level exactly.

The user- and administrator-accessible data includes data in the store:, config:, and local: directories along with data on the compact flash, iSCSI, or RAID volumes included in the backup, if they exist. The data that users and administrators do not have direct access to are keys and password data in the cert:, dpcert:, and sharedcert: directories. Data in an HSM are not backed up, and hence are not included as part of the backup.

Although you can do backups on a working appliance, they should be carefully taken to ensure their usability. Backups of appliances with RAID or iSCSI devices and backups of heavily used appliances may require significant amounts of time.

Encryption and security

User and administrator visible data is encrypted using an ephemeral symmetric key that is encrypted with the public key provided on the secure-backup command before being stored in the manifest file. The visible data includes such things as configuration files, style sheets, and data files. Data from the appliance that users and administrators cannot view, such as private keys, are encrypted twice -- once using an appliance-specific key, and once using the same ephemeral key as the user visible data. Transient data such as logs are not included in the backup.

With the signature of the manifest and the encrypted data files, an administrator can be assured that the backup cannot be manipulated. Without the private key pair of the public certificate used on the backup, the files cannot be restored and used. Since the backup contains private keys and other data, it should be treated like any other critical data and protected appropriately. The idea behind the series of security measures in the secure backup is that an administrator can determine information about the backup from the manifest, but only users with the private key can decrypt the backup. Any attempt to alter the files or the manifest renders the backup invalid and unusable.

Best practices for secure-backup

  • Quiesce the DataPower appliance prior to the secure backup to ensure that all processing activity is ceased.
  • Before backing up an appliance, ensure that all configurations are saved. Only saved data will be backed up.
  • Ensure that configuration files, stylesheets, and other data are not modified during the backup operation.
  • If backups are local, ensure that enough space is available on the appliance.
  • If backups are remote, ensure that the network bandwidth and space in the target directory are sufficient.
  • Due to the amount of time and space required to backup iSCSI and RAID data, it is recommended to use methods other than secure-backup.
  • If iSCSI or RAID data can be backed up using other methods, select the secure-backup switch to exclude backing up iSCSI or RAID data.
  • HSM data is not included in the backup.
  • After backup, protect the backup files as you would any other critical data.
  • Keep the private key of the public certificate used to create the secure backup; it will be required to restore the secure backup
  • After each firmware upgrade or appliance application modification, create a new backup to reflect the current state of the appliance.
  • The firmware at backup time must exactly match the firmware at restore time.
  • You can store the secure backup files locally or remotely. Valid protocols are local, temporary, or ftp.
  • Secure-backup overwrites previous backups when writing to the same destination.
  • You can determine information about the secure backup from the manifest file, but do not attempt to manipulate the tgz files.

Secure-backup from the CLI

The secure-backup command runs from the CLI config mode and has the syntax:

secure-backup certificate destination [include-iSCSI] [include-RAID]

where:

certificate
Specifies the certificate to encrypt the secure backup.
destination
Specifies the URL of the target directory for the backup files; valid protocols are local, temporary, and ftp.
include-iSCSI
Specifies whether the iSCSI device is backed up; the default is on.
include-RAID
Specifies whether the RAID device is backed up; the default is on.

For example:

secure-backup MyCert ftp://ftpuser:passw0rd@ipaddress:port/BackupDir off on

will back up the appliance using the MyCert certificate, to the BackupDir directory on the ftp server, with backup iSCSI off, and backup RAID on.

Secure-backup via the XML-Management Interface

The secure-backup process can be performed by using SOMA or AMP commands.

Sample secure-backup SOMA command:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Body>
<dp:request xmlns:dp="http://www.datapower.com/schemas/management"  domain="default">
   <dp:do-action>
      <SecureBackup>
         <cert>MyCert</cert>
         <destination>ftp://ftpuser:passw0rd@ipaddress:port/BackupDir</destination>
         <include-iscsi>on</include-iscsi>
         <include-raid>on</include-raid>
      </SecureBackup>
   </dp:do-action>
</dp:request>
</env:Body>
</env:Envelope>

Just as with the command line example, DataPower requires the name of the certificate, the destination of the resulting files, and a decision on to include or exclude the iSCSI or RAID data.

Sample secure-backup AMP command:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:amp="http://www.datapower.com/schemas/appliance/management/2.0">
   <env:Body>
      <amp:SecureBackupRequest 
          xmlns:amp="http://www.datapower.com/schemas/appliance/management/2.0">
         <!-- <amp:DoNotIncludeiSCSI/> -->
         <!-- <amp:DoNotIncludeRAID/> -->
         <amp:CryptoCertificateName>MyCert</amp:CryptoCertificateName> 
         <!-- <amp:CryptoCertificate/> -->
         <amp:SecureBackupDestination>
         temporary:///jgsecure-backup.tgz</amp:SecureBackupDestination>
      </amp:SecureBackupRequest>
   </env:Body>
</env:Envelope>

The same required information is present in the AMP command; however, the parameters are entered slightly diffrently. First, the iSCSI and RAID data are still defaulted to be backed up, but are controlled by the amp:DoNotInclude elements. If the iSCSI and RAID are not to be included, the two options need to be uncommented in the XML file. Also, in the AMP command either the certificate name or the actual encoded certificate can be included. Please note that only one or the other may be present. In the above example, if the encoded certificate is added, the <amp:CryptoCertificate> element must be uncommented and the <amp:CryptoCertificateName> element must be commented out.

Secure-backup from the WebGUI

To securely back up the appliance configuration from the WebGUI:

  1. Click Administration => Main => System Control.
  2. Locate the Secure Backup section.
  3. From the Crypto certificate list, select the certificate to encrypt the secure backup.
  4. In the Destination field, enter the URL of the target directory for the backup files.
  5. Optional: For Include iSCSI, specify whether to back up iSCSI data.
  6. Optional: For Include RAID, specify whether to back up RAID data.
  7. Click Secure Backup to back up the appliance.

The iSCSI and RAID options appear only when auxiliary storage is configured on the appliance.

Figure 1. Secure backup from the WebGUI
DataPower Secure backup screen from the WebGUI

Secure-restore

The secure-restore function in DataPower loads configurations and secure data from a secure backup.

Secure-restore basics

To restore a secure backup, you need the private key and public certificate (together they are called a Crypto Identification Credential) that corresponds to the backup files being restored. The backup is a collection of compressed, encrypted files along with a signed manifest. The manifest is signed to ensure data integrity and describes the appliance firmware level, backup date, appliance settings, the certificate used for encryption, and the list the encrypted files with size and checksum. Excluding firmware files allows the backup to be as small as possible but requires that at restore time, the appliance must match the firmware level exactly.

The appliance being restored to must be compatible with the backup files, which means that the exact firmware version and level must be installed on the appliance prior to the restore. The appliance must also have enough space to contain the data in the backup files. For example, if the backup contained iSCSI or RAID data, then the restoring appliance must be configured with the same storage. The restored appliance does not have to be the same machine type, and it can have more storage space than the appliance from which it was backed up.

During the restore process, all data on the appliance is deleted -- the restore process does a complete replacement and does not merge data! Therefore the appliance being restored to should contain only the configuration data needed to do the restore and typically has just been installed or reinitialized.

After the secure-restore is complete, the appliance is rebooted and will assume configurations from the backup that require attention. First, the interface information from the backup files will be assigned to the restored appliance. Before you bring the restored appliance online, you will need to connect via the serial port and configure the interfaces, gateways, and other network configurations, and validate the appliance after reboot. Next, TAM configuration files may also need to be generated again as they are unique for each DataPower appliance. Further, MQ configurations may need to be reset on the restored appliance as there may be multiple appliances listening or writing to the same MQ queues. Finally, if an iSCSI server configuration and data was part of the secure restore, the configuration may need to be updated as multiple appliances may be utilizing the same storage space on the server.

Please refer to the related article mentioned in the Introduction for more detailed outline of post-restore considerations.

During the secure restore process the admin user password is reset to admin. On the initial post-secure restore login, the admin user will be prompted to change the password. All other user passwords from the secure backup will be persisted on the secure restore. The admin user may then reset the passwords of any users that may have changed in the time between backup and restore.

Secure-restore validate option

To verify that backup files will successfully restore to an appliance, a validate option is available. It checks for items such as firmware compatibility, the manifest file's digital signature, and auxiliary storage matches. The validate option performs the validation between the backup files and the appliance to be restored -- it does not initiate the restore. After validation, administrators receive a message saying either that the backup is valid, or that it is invalid along with the reason for the incompatibility. The validate option is not exhaustive. For example, because backup files are compressed, the validate option cannot determine how much space is required for the restore and therefore cannot verify space availability on the restore device. Therefore the validate option may return a positive result, but the ensuing restore may fail.

Best practices for secure-restore

  • Quiesce the DataPower appliance prior to the secure restore to ensure that all processing activity is ceased.
  • Run secure-restore only on a clean (reinitialezed) device.
  • Crypto Identification Credential based on the public certificate used for the secure backup must exist on the restore device.
  • When the restore is complete, you must resolve any differences, such as IP addresses and gateways, between the backup and restored to appliances.
  • Run the restore with validate option before running the actual restore.
  • The secure-restore process reboots the appliance. Therefore, stop any work running on the appliance before you begin the restore.
  • The password for the admin user ID is reset to admin after the restore and must be changed on first login after restore.
  • After you begin a secure restore, you cannot recover any existing data on the appliance.

Secure-restore from the CLI

The secure-restore command runs from the CLI config mode and has the syntax:

secure-restore cryptocred source [validate] [backup-machine-type]

where:

cryptocred
Specifies the crypto identification credential used to decrypt the secure backup.
source
Specifies the URL of the target directory for the backup files.
validate
Specifies whether to validate the backup file; default is off.
backup-machine-type
indicates the platform of the appliance from which the secure backup was created (new to release 4.0.0 and used when going from XI50 to XI52 or XS40 to XG45 appliances)

For example:

secure-restore MyCryptoCred temporary:///MyDir off 9235,

will restore to the appliance using the MyCryptoCred credential, from the MyDir directory from the temporary, with validate the backup off from a backup file from a 9235 machine type

Secure-restore via the XML-Management Interface

The secure-restore process can be performed by using SOMA or AMP commands.

Sample secure-restore SOMA command:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Body>
<dp:request xmlns:dp="http://www.datapower.com/schemas/management"  domain="default">
   <dp:do-action>
      <SecureRestore>
         <cred>MyCryptoCred</cred>
         <source>ftp://ftpuser:passw0rd@ipaddress:port/BackupDir</source>
         <validate>off</validate>
		 <BackupMachineType>9235</BackupMachineType>
      </SecureRestore>
   </dp:do-action>
</dp:request>	
</env:Body>
</env:Envelope>

Just as with the command line example, DataPower requires the name of the crypto credential and the location of the secure-backup files, The validation of the backup files and the backup machine type are optional.

Sample secure-restore AMP command:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:amp="http://www.datapower.com/schemas/appliance/management/2.0">
   <env:Body>
      <amp:SecureRestoreRequest 
	      xmlns:amp="http://www.datapower.com/schemas/appliance/management/2.0">
         <amp:Validate>off</amp:Validate>
         <amp:CryptoCredentialName>myCrypto Cred</amp:CryptoCredentialName>
         <amp:SecureBackupSource>temporary:///secure-backup.zip</amp:SecureBackupSource> 
         <!-- <amp:SecureBackup>base64 Encoded Secure Backup file</amp:SecureBackup> -->
      </amp:SecureRestoreRequest>
	  <amp:BackupMachineType>9235</BackupMachineType>
   </env:Body>
</env:Envelope>

The same required information from the SOMA is present in the AMP command; however, the parameters are entered slightly differntly. One parameter decision to be made is the secure-backup location to be used for the secure-restore. In the above example, the <amp:SecureBackupSource> element is used to point to a file in the DataPower temporary directory. The secure-backup.zip file is a zipped file of the entire directory that contains the secure-backup files. The other option is the <amp:SecureBackup> element. To use this, the entire secure-backup directory is encoded and the resulting text will be entered within the element. Note the XML file will be a large if the latter option is used.

Secure-restore from the WebGUI

To run secure-restore from the WebGUI:

  1. Click Administration => Main => System Control.
  2. Locate the Secure Restore section.
  3. From the Crypto credentials list, select the identification credentials to decrypt the backup.
  4. In the Source field, enter the URL of the source directory from which the backup files will be restored.
  5. Optional: For Validate, specify whether to validate the backup. Default is off.
  6. Optional: For Machine Type, specify the platform of the appliance from which the secure backup was created.
  7. Click Secure Restore to restore the appliance.

The appliance will be rebooted after the secure restore is complete.

Figure 2. Secure-restore from the WebGUI
DataPower Secure-restore screen

Cross-Product secure backup-restore

Secure backup-restore is not supported across product types. In other words, you cannot take a secure backup from an XS40 DataPower appliance and restore it to an XI50 appliance. The only exceptions to this rules is when upgrading from a 9235 XI50 appliance to a 7199 XI52 appliance and from a 9235 XS40 appliance to a 7198 XG45 appliance.

Cross-Platform secure backup-restore

Secure backup-restore is supported, with some exceptions, across differing DataPower appliance hardware for upgrades. You may take a secure backup of a 9235 appliance and restore it to a 4195 appliance. You can also use a backup image from any machine type to restore a 7199 appliance. Be aware however, you cannot use a backup image from a 7199 appliance to restore any machine type except another 7199 appliance.

If restoring from a 9235 or 4195 machine type to a 7199 machine type it is necessary to use the <machine type> option. The DataPower appliance keys were updated for the 7199 machine type and will not match the keys from other machine types.

Secure backup-restore with DataPower on zEnterprise

In general, the secure backup-restore processes with DataPower integrated in a zEnterprise are the same as other platforms; however, a few differences are noted below:.

  • The dp-admin user is configured with policies that will allow the user to perform a secure backup, but will not be configured to perform the secure restore.
  • The secure restore will be done via the HMC.
  • The dp-admin user's password is not updated during the secure restore and retains its value from the backup.
  • The admin user's password is changed to admin during the secure restore process, but the user is not prompted to update the password on initial post-secure restore login. The admin user's password will be updated through the HMC.

Download

DescriptionNameSize
Sample backupmanifest.xml for secure backupbackupmanifest.zip4 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=521957
ArticleTitle=Secure backup-restore for WebSphere DataPower SOA Appliances
publish-date=05302012