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
The IBM WebSphere Appliance Management Toolkit (often referred to as "the manager") is designed for managing groups of DataPower devices.
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:
Synchronization of configuration changes across a set of devices
- Make configuration changes one time and synchronize them to a set of devices.
The synchronization can be controlled to apply changes during maintenance windows.
Support configuration lifecycle deployment
- Promote configuration between various environments (i.e. Development, Test, Production).
- Deployment policies are used to support environment-specific configuration changes. The environment-specific changes are configured one time and reused for each deployment.
Support heterogeneous devices in a single ManagedSet of devices
- Allow devices with different hardware types
- Allow devices with different firmware levels
- Allow devices with different license features
Centralized firmware management
- Firmwares are stored in a centralized data repository.
- Controlled firmware deployment to allow for upgrades during maintenance windows
Disaster Recovery
- Complete backup of configuration, files, crypto material, and user credentials
- Restore the backup to the device or a new compatible device
Data Repository interface for persisting artifacts and configurations
- Pluggable interface to allow support for various data repositories
- Persists manager meta-configuration about devices, firmwares, managed sets
- Persists domain configuration versions
- Persists firmware versions
- See Architecture for more information.
Support quiesce of data traffic to allow existing transactions to complete
- Configuration changes are applied after a domain is quiesced
- Firmware upgrades are performed after the device is quiesced
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.
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.
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.
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.
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
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
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 classes that use the IBM WebSphere Appliance Management Toolkit will require the following jars in their classpath:
- WAMT-1.5.1.0.jar
- stax-api-1.0.1.jar
- xbean.jar (version 2.4.0)
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.
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.
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.
- Create the Manager
- Create a new ManagedSet
- Create a Device(s)
- Add Device(s) to a ManagedSet
- Add Domain(s) to be managed on the Device(s)
- Set the configuration and deployment policy for managed Domains
- For manual deployments, set the Domain synchronization to manual mode
for the managed Domains
- For automatic synchronization, set the Domain synchronization to automatic mode
for the managed Domains
There are several mechanisms to help with the debugging of the manager:
- widen the logging level: it may be increased all the way to
FINEST
for the most detail. Generally FINE
or FINER
should be sufficient to see the program flow. The manager uses JSR47 logging,
and has a hierarchy of loggers. Please refer to the topmost
package javadoc for the details of adjusting and consuming logging
data.
- The manager offers a rich hierarchy of exceptions. The intention is
that the exception class should provide enough information to determine
what the error is. Start with the topmost exception class,
DMgrException
,
and drill down through the rest of the exception tree.
The root class for exceptions thrown from the manager is DMgrException.java.
All exceptions classes are more specific sublasses of this exception.
The following is a list of Exceptions that must be handled by classes that use the manager
See the details on amp Exceptions
in the amp Exception Summary
See the details on clientAPI Exceptions
in the clientAPI Exception Summary
See the details on dataAPI Exceptions
int the dataAPI Exception Summary
© Copyright IBM Corp. 2006, 2010 All Rights Reserved.