IBM WebSphere Appliance Management Toolkit

The IBM WebSphere Appliance Management Toolkit (often referred to as "the manager") is designed for managing groups of DataPower devices.

See:
          Description

Packages
com.ibm.datapower.wamt This package contains classes that are used by the clientAPI and amp packages.
com.ibm.datapower.wamt.amp The Appliance Management Protocol (AMP) provides an abstraction layer for message and command communication between the Manager and the DataPower devices.
com.ibm.datapower.wamt.clientAPI The clientAPI package encapsulates the logic for managing DataPower appliances, providing the API that should be used by a user interface to interact with one or more appliances.
com.ibm.datapower.wamt.dataAPI Defines a collection of interfaces for data persistence that can be implemented to support a repository in various environments.
com.ibm.datapower.wamt.dataAPI.local.filesystem Local File System Implementation of the dataAPI Interface for the IBM WebSphere Appliance Management Toolkit
com.ibm.datapower.wamt.soma  

 

The IBM WebSphere Appliance Management Toolkit (often referred to as "the manager") is designed for managing groups of DataPower devices.

Overview

The IBM WebSphere Appliance Management Toolkit is designed for managing groups of DataPower devices, which are referred to as ManagedSets. A ManagedSet represents a collection of DataPower devices which provide similar services and contain similar configurations.
This overview covers the following topics:


Features

Synchronization of configuration changes across a set of devices

Support configuration lifecycle deployment

Support heterogeneous devices in a single ManagedSet of devices

Centralized firmware management

Disaster Recovery

Data Repository interface for persisting artifacts and configurations

Support quiesce of data traffic to allow existing transactions to complete


Architecture



architecture diagram

clientAPI

The clientAPI is a task level API for managing groups of DataPower devices. The manager does not provide a user interface, so the clientAPI is provided so its consumers can provide their own. The manager needs to be configured and instantiated by a higher-level application.

Please refer to the information in clientAPI package for more details.

dataAPI

The manager offers a pluggable data repository mechanism via the dataAPI. The manager persists data, such as definitions of devices and managed sets, as well as large binary objects of firmware, and versions of domain configurations and deployment policies. The dataAPI was designed as a pluggable with the expectation that different runtime environments would use different persistence technologies (DB2, WCCM, Local File System, CVS, etc...).

A Local File System implementation is provided as the the default dataAPI implementation. See the section on Dynamically-loaded drivers for information on specifying another dataAPI implementation.

clientAPI objects which are persistable will implement the Persistable interface. There also is a PersistenceMapper which correlates clientAPI objects with dataAPI/Stored* objects. See the dataAPI summary for more information.

Appliance Management Protocol

The manager uses the Appliance Management Protocol (AMP) to communicate with DataPower devices. AMP is a SOAP-based protocol for management of DataPower devices.

Please refer to the information in the AMP package for more details.


Object Model for the IBM WebSphere Appliance Management Toolkit

There is one top-level object that is required before any other objects may be used: Manager . The Manager object is a singleton and is needed to create all other objects.

Once you have created the Manager you can create Device objects that represent DataPower devices and perform clientAPI management tasks with them. Refer to Device for more details on the operation that may be performed on a Device objects. You can then add the Devices objects as members of a ManagedSet object and manage them collectively as a set.

Other objects that the manager uses when interacting with a device are:

Note that the Firmware, Domain, and DeploymentPolicy objects are Versionable. A Versionable object can have a collection of Versions. For example, a Firmware object can have a collection of FirmwareVersions. The data associated with a particular version is stored in the Version object instead of the Versionable object. Refer to the list of classes which implement the Versionable and Version interfaces.

See the diagram below for visual representation of the relationship of the Java objects used by the manager.

object relationship count diagram

Setup

Java Version

The manager requires Java version 1.5 or later. It is recommended that you upgrade to the latest fixpack. To determine the version of java you have installed type the following command.
    java -version

JVM settings

Due to the large size of firmware files, it is recommended that the heap size of the Java virtual machine be set to at least 768MB. Otherwise you may encounter out-of-memory errors from the JVM, especially when dealing with firmware images. The following example causes Java to set an initial heap size of 768MB and a maximum of 1024MB. (Note: These values are sample values - suitable values may differ for your specific application.

Example:
   java -Xms768m -Xmx1024m YourClass

Configuration

An optional properties file may be used to govern the behavior of the manager if the configuration defaults are not desirable (Example: You may want to change the domain synchronization interval). To override defaults place a file called WAMT.properties in the current directory or the directory specified by the WAMT_CONFIGURATION_HOME JVM parameter. (e.g. the following example causes the manager to expect a configuration file C:\DataPowerConfig\WAMT.properties.)
Example:
   java -DWAMT_CONFIGURATION_HOME="C:\DataPowerConfig" YourClass
See the javadoc on Configuration for a list of the properties that can be specified. The properties in the file should be organized as a list of key=value pairs, with one key/value pair per line. The keys can be determined by inspecting the Constant Field Values for the configuration (look for constants KEY_ for the property name and DEFAULT_ for the default value for each property. Valid values vary based on the property.

You can also supply a logging.properties file to the runtime by specifying a java.util.logging.config.file JVM parameter. The following example causes the manager to expect logging configuration file at C:\DataPowerConfig\logging.properties.

Example:
   java -Djava.util.logging.config.file="C:\DataPowerConfig\logging.properties" YourClass
See the Debugging section for more details.

Java Classpath

Java classes that use the IBM WebSphere Appliance Management Toolkit will require the following jars in their classpath:

Pluggable Repository Driver

The manager requires a run-time repository to persist configuration information. The default repository is a local file system implementation, but an alternate implementation may be specified at Manager start-up. This is accomplished by identifying the implementation class name in the WAMT.properties file described above, or as an option when the Manager is instantiated. The purpose of making the repository implementation pluggable is to allow alternate implementations to be provided based on requirements. The interface description for com.ibm.datapower.wamt.dataAPI.Repository may be found here. The default implementation class name is com.ibm.datapower.wamt.dataAPI.local.filesystem.RepositoryImpl.

Sample code to specify an alternate repository implementation as an option on Manager construction:


Map options = new HashMap();
options.put(Manager.OPTION_REPOSITORY_IMPL, "com.yourco.com.RepositoryImpl");
Manager manager = Manager.getInstance(options);

Other manager options may be specified at start-up. Please see Manager.getInstance(Map) and Configuration for more information on manager options.

Network Communications

It is assumed that there is steady bi-directional communication connectivity between the devices and the manager. The devices send AMP events to the manager. The manager sends AMP commands to the devices.

The default listening port for the device is 5550, which is the device's XML Management Interface. The manager will send AMP commands to this port on the device, and the TCP connection will be initiated by the manager from an ephemeral port on the manager.

The default listening port for the manager is 5555, which is the manager's NotificationCatcher port. The device will send AMP events to this port on the manager, and the TCP connection will be initiated by the device from an ephemeral port on the device.

Any firewalls between the devices and the manager need to permit this traffic, otherwise management will not be able to occur.

The communication between the manager and devices in both directions uses SSL by default without client authentication. This is to provide link-level security. Doing a packet trace will not result in any usable information. If you want to debug the manager look in the Debugging section below.

Sample ManagedSet Setup

The clientAPI package description provides sample code describing how to set up a ManagedSet of DataPower devices to deploy configuration to the set of devices.

Debugging

There are several mechanisms to help with the debugging of the manager:



© Copyright IBM Corp. 2006, 2010 All Rights Reserved.