Restoring transaction metadata and document payloads for WebSphere DataPower B2B Appliances

This article describes how to restore historical transaction metadata and document payloads to another compatible WebSphere® DataPower B2B Appliance without permanently losing data.

Share:

Debbie Kuo (debbiek@tw.ibm.com), Staff Software Engineer, IBM

Photo of Debbie KuoDebbie Kuo is a Staff Software Engineer and joined the WebSphere DataPower testing team in 2008. She has worked as a test lead on B2B Appliance for B2B High Availability, ebMS2 messaging integration, interoperability testing with WebSphere Partner Gateway, CPA implementation and other B2B protocols. Her past testing projects included SNMP, logging, WebGUI, and z/OS interoperability features in DataPower.



Giant Tu (ganttu@tw.ibm.com), Advisory Software Engineer, IBM

Photo of Giant TuGiant Tu is a Staff Software Engineer and joined the WebSphere DataPower team in 2006. He has been involved with many projects, including SQA, MQ testing, WTX development, logging development, RAID development, and platform support. He was the major developer for the RAID functionality and platform-related area.



Johnson YS Chiang (chiangys@tw.ibm.com), Staff Software Engineer, IBM

Photo of Johnson ChiangJohnson Chiang is a Staff Software Engineer on the WebSphere DataPower Appliance development team. Johnson has worked as a lead developer on B2B Appliance for DataPower's connectivity over B2B protocols, including EDI via AS1/2/3, and ebMS messaging integration with the ebXML framework. His past projects also included B2B High Availability, appliance management functionality, MQ messaging, and NAS/SAN features.



27 February 2013

Introduction

This article provides steps on how to restore historical transaction metadata and document payloads to another compatible WebSphere DataPower B2B Appliance without permanently losing data. You can store your transaction metadata and document payloads on the provided redundant array of independent disk (RAID) drives, which is the default setting at initial firmware setup. However, when you experience an appliance hardware related issue, it is critical to restore the historical transaction metadata and document payloads on another compatible appliance without any loss. By using a sequence of commands, you can simply bring up the original RAID drives and access all transaction metadata and document payloads on another compatible appliance.

Note:

This article applies only to the RAID encryption method that is set to "passphrase" on the appliance.

The following topics are presented in this article:

  • Overview of the two use cases
  • Overview of the RAID devices on the DataPower B2B Appliance XB60 and XB62
  • Using the setting of the RAID encryption method
  • Testing B2B transactions on compatible DataPower B2B Appliances
  • Importing the backup domains to the compatible DataPower B2B Appliances
  • Moving the original hard drivers to the compatible DataPower B2B Appliances
  • Reactivating the hard drives on the compatible DataPower B2B Appliances
  • Verifying the historical B2B transaction on the compatible DataPower B2B Appliances

Overview of the B2B transaction metadata and document payloads

The B2B Gateway service in DataPower B2B Appliances is the primary service used for facilitating business to business traffic over the standard messaging protocols (AS1, AS2, AS3, and ebMS2). All transactions processed by a B2B Gateway service will store the data in metadata storage and document storage as shown in Figure 1.

Figure 1. DataPower B2B Appliance XB60 and XB62 components
DataPower B2B Appliance XB60 and XB62 components

Metadata storage

All B2B gateways use the persistent store to store metadata about the transactions. This metadata is stored in the unencrypted partition of the hard drives.

Document storage

Each B2B gateway, on a service-by-service basis, can store copies of message documents, such as inbound messages, outbound messages, acknowledgement messages, and MDN messages. This space is shared across all B2B gateways. By default, these documents are saved in the encrypted partition of the hard drives.


System requirements

The appliance being restored must be compatible with the backup appliance, which means both appliances have the identical hardware model, firmware version, and storage capacity. For example, you cannot restore the backup from a WebSphere DataPower B2B Appliance XB60 to an Appliance XB62, given the differences of the hardware model and hard drive specifications between those two appliances.

There are two supported options to store B2B transactions: RAID and NFS.

RAID

If you are applying a RAID volume as an in-box document storage, you must encrypt the RAID with the "passphrase" method.

NFS

If you are applying the Network File System (NFS) mount as an off-box document storage, follow the RAID replacement procedures in the Using the settings of the RAID encryption method section to restore the transaction metadata. For the document payloads stored in the NFS server, the only way to restore the payloads is to ensure that the "Document Storage Location" in the B2B Gateway configuration points to the correct URL, such as dpnfs://mount-name/path.


Overview of the use cases

Moving transaction metadata and document payloads from one B2B appliance to the other can occur in some cases. The following are two use cases you may face. This article provides instructions on how to restore the metadata and payloads.

Use Case 1: Appliance reaches the end of life

This use case restores B2B transactions to another WebSphere DataPower B2B Appliance XB60 and XB62 due to a hardware replacement. If a hardware failure occurs on the B2B appliance or if any appliance reaches the end of life, you can follow the instructions to restore the existing B2B transaction metadata and payloads on the new appliance by simply switching the RAID devices.

Use Case 2: Move B2B transactions to the testing environment for development

This use case moves the transaction metadata and document payloads from a production environment to a testing environment for issue investigation or for new B2B service development. After the development or investigation is done, you can use the instructions to restore the transactions and payloads to the production appliance for continued service.


Overview of the RAID devices on DataPower B2B Appliance XB60 and XB62

You need to know the location of the hard drive on the XB60 and XB62 appliances when moving the hard drives to a compatible appliance. The following figures show the differences between the XB60 and XB62 appliances.

WebSphere DataPower B2B Appliance XB60

WebSphere DataPower B2B Appliance XB60 is a 1U system equipped with two hard drives in one hard disk tray, located at the back of the appliance. These two disks are configured as RAID 1, as shown in Figure 2.

Figure 2. Rear view of WebSphere DataPower B2B Appliance XB60
Rear view of WebSphere DataPower B2B Appliance XB60

The label in Figure 2 corresponds to the following component in the rear panel of a XB60 appliance:

  • A: The data storage unit - hard disk array

WebSphere DataPower B2B Appliance XB62

WebSphere DataPower B2B Appliance XB62 is a 2U system equipped with four hard drives, located on the front of the machine. These four disks are configured as RAID 10, as shown in Figure 3.

Figure 3. Front view of WebSphere DataPower B2B Appliance XB62
Front view of WebSphere DataPower B2B Appliance XB62

The labels in Figure 3 correspond to the following components on the front panel of the XB62 appliance:

  • A: Hard disk drive module 0
  • B: Hard disk drive module 1
  • C: Hard disk drive module 2
  • D: Hard disk drive module 3

Using the settings of the RAID encryption method

To use the instructions in this article, you need to have the encryption setting of "passphrase". The reason is that the system key is unique across each appliance. It cannot be shared with and used by other appliances so that the partition cannot be read by others if the system key is used in the encryption.

In the initial firmware setup of a XB62 appliance, the document storage partition on the RAID drive is encrypted with the passphrase method by default. In the initial setup of a XB60 appliance, the default settings in the initial firmware setup use the internal system key method. You can change the encryption settings for the document storage partition on the RAID drive in the "default" domain.

You need to change the partition encryption setting to "passphrase" on the new compatible appliance before restoring the historical transaction metadata and document payloads on it. If you already had the hard disk array encrypted with passphrase on the new appliance, you do not need to perform this step again. Go to the next section to import the backup domains on the new appliance.

Changing the partition encryption settings to passphrase from the WebGUI

To change the encryption setting for the document storage partition of the hard disk array:

  1. Click Objects > System > Hard Disk Array.
  2. Click the name of the hard disk array to display the configuration screen.
  3. Change Administrative State to disabled.
  4. Click Apply.
  5. Click the Change Partition Encryption Settings link in the upper right corner.
  6. Change the settings to Passphrase.
    • Encrypt Local Drive: on
    • Encryption Method: Use Passphrase
    • New Passphrase: Type the desired password twice.
  7. Click Change Partition EncryptionSetting button.
  8. Follow the prompts.

    Do not close the prompt dialogs until you receive the message that the action has completed successfully. While the appliance performs this action, do not perform another action against the array.

  9. After the action completes, enable the hard disk array:
    1. Change Administrative State to enabled.
    2. Click Apply.
  10. Go to Status > System > Raid Partition Status. Check if Encryption Method for Partition2 has changed to User Passphrase, as shown in Figure 4.
    Figure 4. Check Encryption Method in RAID Partition Status
    Check Encryption Method in RAID Partition Status

Changing the partition encryption setting to passphrase from the CLI

  1. Disable the RAID volume (raid0) as follows:
    xb60(config)# raid-volume raid0;admin disabled;exit
  2. Change the encryption setting on the document storage partition as follows:
    xb60(config)# raid-change-encryption-settings
    Usage: raid-change-encryption-settings <name> <encrypt> [<method> [<passphrase>]]
    xb60(config)# raid-change-encryption-settings raid0 on passphrase datapower
  3. Enable RAID volume as follows:
    xb60(config)# raid-volume raid0;admin enabled;exit
  4. Check the status of the RAID partitions. The Encryption Method for the "b2bPersistence" partition must be userPassphrase as follows:
    xb60(config)# sh raid-partition
    Volume  Partition Purpose Encryption Algorithm Encryption Method Total      Free
    Name                                                             Size       Space
    ------- --------- ------- -------------------- ----------------- ---------- --------
    raid0    1    localStorage   None-Unsupported  na                70500856   70304688
                   
    raid0    2    b2bPersistence aesSha            userPassphrase    70500856   70316640

Testing the B2B transactions on compatible DataPower B2B Appliances

This step is used to ensure that the RAID is encrypted with passphrase. After the partition is encrypted with passphrase, you can test, send, or receive a few B2B transactions to ensure that:

  • You can view the new transactions on the B2B Viewer (see Figure 5).
  • You can download the input, output, content, and MDN and ACK files for each transaction on the B2B Viewer.
    Figure 5. Verify transactions on B2B Viewer
    Verify transactions on B2B Viewer

Importing backup domains to the compatible DataPower B2B Appliances

You need to import the backups of the system or domains to the target device where the data will be restored. Before importing, ensure you have completed the steps in The settings of RAID encryption method section on the target device. After importing to the target device, if you are using NFS as document storage, ensure the B2B Gateway has the correct NFS URL in the Document Storage Location field and the NFS mount is operational.

Note: It is a best practice to back up your system and domains before any configuration change.

To import, simply go to Default domain > Control Panel > Import Configuration > (select your backup file) > Next > Restore your domains.


Moving the original hard drivers to the compatible DataPower B2B Appliances

Now you need to power off the old WebSphere DataPower B2B Appliance XB60 or XB62 and move the hard drives from the old appliance to the target appliance.

Note: You need to power off the replacement DataPower B2B Appliance to avoid a hardware failure.

Because the hard drives are configured as RAID, follow the instructions below to move the hard drives to the right positions on the target appliance.

WebSphere DataPower B2B Appliance XB60

Insert the hard drives from the old appliance to the corresponding location as shown in Figure 6.

Figure 6. Move the hard drives to a new B2B Appliance XB60
Move the hard drives to a new B2B Appliance XB60

WebSphere DataPower B2B Appliance XB62

When moving the hard drives from DataPower B2B Appliance XB62 to another replacement XB62, the old hard drives need to be inserted into the corresponding locations correctly as shown in Figure 7.

Figure 7. Move the hard drives to a new B2B Appliance XB62
Move the hard drives to a new B2B Appliance XB62

Reactivating the hard drives on the compatible DataPower B2B Appliances

Perform the following actions on the new B2B Appliance to continue the B2B transaction migration:

  1. Power on the new DataPower B2B Appliance XB60 or XB62.
  2. Import the backup B2B domains to the new B2B Appliance XB60 or XB62.
  3. Disable the hard disk array either from the CLI or the WebGUI as follows:
    xb60(config)# raid-volume raid0;admin disabled;exit
    Modify Hard Disk Array configuration
    % Error making storage volume inaccessible
  4. Reactivate the hard disk array on the new XB60 or XB62 appliance.

Reactivating the RAID from the CLI

Reactivate the RAID from the CLI as follows:

xb60(config)# raid-activate
Usage: raid-activate <name>
xb60(config)# raid-activate raid0

Reactivate RAID from the WebGUI

To reactivate RAID from the WebGUI:

  1. Click Objects > System > Hard Disk Array. Click the name of the hard disk array to display the configuration screen.
  2. Click the Activate Array link in the upper-right corner.

Reconciling the partition encryption settings

This section describes how to reconcile partition encryption settings, and then enable the hard disk array.

Reconcile the RAID partition from the CLI

Reconcile the RAID partition from the CLI as follows:

xb60(config)# raid-reconcile-encryption-settings
Usage: raid-reconcile-encryption-settings <name> <encrypt>
[<method> [<passphrase>]]
               
xb60(config)# raid-reconcile-encryption-settings raid0 on passphrase datapower

xb60(config)# raid-volume raid0;admin enabled;exit
Modify Hard Disk Array configuration

xb60(config)# sh raid-volume raid0
raid-volume: raid0 [up]               
------------------
 admin-state enabled
 directory ondisk

Reconcile the RAID partition from the WebGUI

To reconcile the RAID partition from the WebGUI:

  1. Click Objects > System > Hard Disk Array. Click the name of the hard disk array to display the configuration screen.
  2. Click the Reconcile Partition Encryption Settings link in the upper-right corner.
  3. After it completes, change the Administrative State of hard disk array from disabled to enabled.
  4. Ensure the op-state of the hard disk is "up".

Verifying the historical B2B transaction on the compatible appliances

After bringing up the original hard drives to the target appliance, the next step is to ensure all the historical transaction metadata and document payloads are showing on the B2B Viewer of the target appliance without any metadata or message payload loss.

Before verifying B2B transactions, you need to perform the steps in the following sections.

Enabling the B2B persistence from the CLI

Enable from the CLI as follows:

xb60(config)# b2b-pers;admin enabled;exit
Modify B2B Persistence configuration
% Pending
xb60(config)# sh b2b-pers
b2b-persistence [up] (modified)
---------------
 admin-state enabled
 raid-volume raid0 [up]

Enabling the B2B persistence from the WebGUI

To enable from the WebGUI:

  1. Click Objects> System Settings > B2B Persistence.
  2. Set the Administrative State to enabled.
  3. Click Save Config to save the changes to the startup configuration.
  4. Ensure that the op-state of B2B persistence is up.
  5. Go to Control Panel > B2B Viewer. You see that all the historical transaction metadata and document payloads are now showing up on the new DataPower B2B Appliance XB60 or XB62 and you can download the document payloads, as shown in Figure 8.
    Figure 8. Verify the B2B Viewer on the new DataPower B2B Appliance XB60 or XB62
    Verify the B2B Viewer on the new DataPower B2B Appliance XB60 or XB62

Conclusion

This article described how to restore the transaction metadata and document payloads on a compatible appliance. The key point is to use the "passphrase" method in the RAID partition encryption. By doing so, you can bring up the transaction metadata and document payloads between the compatible B2B appliances and achieve high reliability of the B2B transactions when you encounter a hardware failure or other unexpected failures.

Resources

Learn

Discuss

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=859680
ArticleTitle=Restoring transaction metadata and document payloads for WebSphere DataPower B2B Appliances
publish-date=02272013