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.
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.
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]
- Specifies the certificate to encrypt the secure backup.
- Specifies the URL of the target directory for the backup files; valid protocols are local, temporary, and ftp.
- Specifies whether the iSCSI device is backed up; the default is on.
- Specifies whether the RAID device is backed up; the default is on.
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:
- Click Administration => Main => System Control.
- Locate the Secure Backup section.
- From the Crypto certificate list, select the certificate to encrypt the secure backup.
- In the Destination field, enter the URL of the target directory for the backup files.
- Optional: For Include iSCSI, specify whether to back up iSCSI data.
- Optional: For Include RAID, specify whether to back up RAID data.
- 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
The secure-restore function in DataPower loads configurations and secure data from a secure backup.
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]
- Specifies the crypto identification credential used to decrypt the secure backup.
- Specifies the URL of the target directory for the backup files.
- Specifies whether to validate the backup file; default is off.
- 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)
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:
- Click Administration => Main => System Control.
- Locate the Secure Restore section.
- From the Crypto credentials list, select the identification credentials to decrypt the backup.
- In the Source field, enter the URL of the source directory from which the backup files will be restored.
- Optional: For Validate, specify whether to validate the backup. Default is off.
- Optional: For Machine Type, specify the platform of the appliance from which the secure backup was created.
- 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
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.
|Sample backupmanifest.xml for secure backup||backupmanifest.zip||4 KB|
- WebSphere DataPower SOA Appliances developer resources page
Technical resources to help you use WebSphere DataPower SOA Appliances to simplify, secure, and accelerate XML and Web services deployments within an SOA..
DataPower SOA Appliances product page
Product descriptions, product news, training information, support information, and more.
- WebSphere DataPower SOA Appliances product library
Product announcements, case studies, white papers, and more.
- WebSphere DataPower SOA Appliances documentation
Complete documentation for the DataPower XA35, XS40, XI50, XB60, and XM70 Appliances.
- WebSphere DataPower SOA Appliances support
A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
- WebSphere DataPower SOA Appliances forum
Get answers to your technical questions and share your expertise with other WebSphere DataPower users.
- WebSphere DataPower SOA Appliance Handbook
This retail book shows you how to use DataPower Appliances from the network, security, and ESB perspectives. The book describes installation, configuration, management, monitoring, configuration, build, deployment, DataPower as a network device, and DataPower services, especially the "big three" of XML Firewall, Web Service Proxy, and Multi-Protocol Gateway.
- IBM Redbook: IBM WebSphere DataPower SOA Appliances, Part I:
Overview and getting started
DataPower SOA appliances are purpose-built, easy-to-deploy network devices that simplify, secure, and accelerate your XML and Web services deployments while extending your SOA infrastructure. This IBM Redbook describes DataPower architecture, use cases, deployment scenarios, and implementation details, as well as best practices for SOA message-oriented architecture in a production ESB legacy environment.
- IBM Redbook: IBM WebSphere DataPower SOA Appliances Part II:
Authentication and Authorization
This IBM Redbook includes the following DataPower authentication and authorization topics: basic concepts, creating policies, using Tivoli Access Manager, and using LDAP directories.
- IBM Redbook: IBM WebSphere DataPower SOA Appliances Part III: XML
This IBM Redbook describes how to use a DataPower appliance to secure incoming Web Services within an SOA environment, how to integrate your DataPower appliance with WebSphere Message Broker, and how to protect against security attacks by implementing the XML Denial of Service (XDoS) provided by DataPower appliances.
- IBM Redbook: IBM WebSphere DataPower SOA Appliances Part IV:
Management and Governance
This IBM Redbook describes how to integrate a DataPower appliance with other products such as WebSphere Registry and Repository, IBM Tivoli Composite Application Manager for SOA, and Tivoli Composite Application Manager System Edition.
WebSphere developer resources
Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
- developerWorks WebSphere application connectivity developer
How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
- developerWorks WebSphere weekly newsletter
The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
- WebSphere-related books from IBM Press
Convenient online ordering through Barnes & Noble.
- WebSphere-related events
Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks Webcasts
Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
Listen to interesting and offbeat interviews and discussions with software innovators.
- developerWorks on
Check out recent Twitter messages and URLs.
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.