This chapter describes how to install and configure Business Transaction Management on IBM WebSphere.
Please note the following third-party requirements and environment settings:
Business Transaction Management requires Macromedia Flash v9 or higher.
If you are using Internet Explorer, you must configure the browser to allow the Flash player Active X control. Consult your Internet Explorer documentation for instructions on enabling this setting.
If you are using a Windows Firewall, you need to configure the firewall to make it aware of each port into which you install Business Transaction Management. Consult your Microsoft Windows documentation for instructions.
If you are running Business Transaction Management on Unix-like systems, you must restart your web server with the following property set before you run reports using the Business Transaction Management performance component:
-Djava.awt.headless=true
If you are installing Business Transaction Management into an HTTPS environment, you must ensure that your network conforms to the following conditions before you configure Business Transaction Management:
Every component of your network that is registered with the Business Transaction Management sphere must be running SSL, and must communicate through the same Business Transaction Management sphere entry URL and port.
You cannot mix HTTP and HTTPS URLs or ports within your Business Transaction Management servers.
All application server names within your network must resolve consistently. In other words, application servers must be known to all components by the same host name.
Communications between Business Transaction Management components are secured by way of a trusted assertions. This means that for your Business Transaction Management components to communicate with each other, and for your Business Transaction Management installation to function properly, every Business Transaction Management component (except for Business Transaction Management observers) must be configured with the same value for the shared secret.
Business Transaction Management also encrypts sensitive data contained in the communications between its components. It encrypts this data for both on-the-wire communications and storage in the Business Transaction Management databases.
These security mechanisms are enabled by default, and all Business Transaction Management components are preconfigured with a default value for both the shared secret and the encryption key. This default security configuration fully enables the security mechanisms and, at the same time, simplifies the installation of Business Transaction Management.
However, because every Business Transaction Management installation uses the same default values, using the default values is a potential security threat. For demonstration purposes, and perhaps for development environments, using the default values might be adequate. But, in production environments, you should tighten security by providing your own unique values. You should also use your own values in your test environment before deploying Business Transaction Management into your production environment. If you intend to provide your own values, you should perform that configuration on each machine hosting a Business Transaction Management component before you deploy the component (machines hosting only Business Transaction Management observers do not need to be configured in this way).
You must configure the shared secret on each WebSphere server that hosts a Business Transaction Management component other than a Business Transaction Management observer. To configure the shared secret, create a Java system property named com.amberpoint.IdentityAssertion.SharedSecret in the server and set its value to your shared-secret string, for example:
-Dcom.amberpoint.IdentityAssertion.SharedSecret=MySecretString
where MySecretString is your own secret string.
You must configure the encryption key on each WebSphere server that hosts a Business Transaction Management component other than a Business Transaction Management observer. To configure the encryption key, create a Java system property named com.amberpoint.security.encryption.aes.defaultKey in the server and set its value to your encryption key, for example:
-Dcom.amberpoint.security.encryption.aes.defaultKey=MyEncryptionKey
where MyEncryptionKey is a base 64-encoded, AES, 128-bit key.
Business Transaction Management provides a command line tool utility named genseckey.bat that you can use to generate a base 64-encoded, AES, 128-bit key. You can access this utility after you download and unzip the Business Transaction Management distribution ZIP file. The utility is located in the tools directory at the top level of the expanded archiveTo generate a base 64-encoded, AES, 128-bit key, run the utility without any flags, for example:
C:> genseckey
Provider = SunJCE
Algorithm = AES
Key strength = 128 bits (in 16 bytes)
Key value = oylJKoTGXTHasOYwtjwA7g==
Note that in this example, the generated key happens to include two equal symbols (==) at the end of the string.
After generating your encryption key, you can copy and paste it in order to set the value of your com.amberpoint.security.encryption.aes.defaultKey property. If your key includes special characters, you should enclose it in double quotes, for example:
-Dcom.amberpoint.security.encryption.aes.defaultKey="oylJKoTGXTHasOYwtjwA7g=="
If you are using a external database, add the appropriate database driver to the WebSphere CLASSPATH. (Drivers are supplied in the Business Transaction Management distribution in the install_dir/jdbc directory)
If you edit the CLASSPATH while the server is running, be sure to restart WebSphere before configuring Business Transaction Management.
Install ap-mto-runtime.jar into the WAS_install_dir/lib directory of every server that hosts the container service (servers hosting apMain, apContainer, apMonitorNode, apProxyNode, apPerformanceServer, and apTransactionServer). Business Transaction Management supplies this file in install_dir/ archives. Note that if you do not install ap-mto-runtime.jar into the server running apMain, several Business Transaction Management system services will be displayed as degraded in the Business Transaction Management Console.
Use the WebSphere Administrative Console to specify Initial Heap Size of no less than 256, and Maximum Heap Size of no less than 1024.
Enable global security on WAS.
Set up an administrative user.
Business Transaction Management maps roles defined in WebSphere to its own application roles. See Chapter 2, "Mapping Users to Business Transaction Management Application Roles".
The Business Transaction Management Console uses roles to authorize access to various parts of the user interface.
To configure Business Transaction Management, you must log in as a user with the amfadmin role. For information on setting up user accounts and assigning roles, see the “Authentication and Role Mapping” topic in the Business Transaction Management online help.
The application roles of Business Transaction Management administrator (amfadmin, slmadmin, exmadmin) are automatically mapped to the Administrators group on Windows systems, or the adm, sys, and bin groups on Unix-like systems. The roles of BTM user (amfuser, slmuser, exmuser) and observer (amfobserver, slmobserver, exmobserver) are mapped to all authenticated users on your system. Note that the default mapping assumes the WebSphere security value of Local OS setting for the Active user registry setting. If you are using a different security setup, you may have to remap users/groups based on your authentication domain settings. The table below lists the Business Transaction Management application roles and their default container role mapping:
Table 2-1 Role Mapping in WebSphere
| Business Transaction Management Application Roles | Container Group |
|---|---|
|
amfadmin slmadmin exmadmin |
Administrators |
|
amfuser slmuser exmuser amfobserver slmobserver exmobserver amf_limited_observer slm_limited_observer exm_limited_observer amf_proxy_user |
all authenticated users |
|
exm_inspector |
exm_Inspector |
|
exm_superinspector |
exm_superinspector |
You can change these mappings using the WebSphere Administrative Console. For information on setting up user accounts and assigning roles, see the “Authentication and Role Mapping” topic in the Business Transaction Management online help. Log in to the Business Transaction Management Console using credentials from an account in one of these groups.
Several Business Transaction Management system services use a database to store persistent information. In addition, another database is used to store agent message logs. The embedded database is supplied primarily for demonstrations and for situations where you will not need to migrate data. We encourage you to use an external, enterprise database management system when you initially configure Business Transaction Management, as migrating between different database systems at a later time is typically complicated). The following enterprise database management systems are supported for use with Business Transaction Management running on a WebSphere server:
Oracle 10g
Oracle 11g
MS SQL Server 2000
MS SQL Server 2005
IBM DB2 UDB v.8.1
Sybase ASE 12.5
Before you configure Business Transaction Management, create the following databases (these are suggested names):
sphereServiceDB
performanceDB
exmServiceDB
agentServiceDB
You must create the databases before starting configuration of Business Transaction Management. When you configure Business Transaction Management (see Chapter 2, "Configuring Business Transaction Management"), the system will automatically create the database tables. If you intend to let the system automatically create the tables, the user under which the database is run must have create table, create index, and create view privileges. (Note: For an Oracle database is not sufficient to assign the privileges to the roles associated with the user. You must explicitly assign the privileges to the user.)
Note:
If your DBA wants to create the database tables manually, Business Transaction Management supplies thedatastoreUtil tool, located in the install_dir\tools directory. This utility generates the appropriate schema definitions. Please refer to the Business Transaction Management online documentation for information about this tool.Put the database driver in the classpath of your application server.
Each Business Transaction Management database must be in a separate schema. For example, if you are using an Oracle RDBMS you must create a separate user for each Business Transaction Management database.
If you are preparing an IBM DB2 UDB database, you must ensure that it is configured with 16k table space, 16k user temporary table space, and 16k system temporary table space (by default, IBM DB2 UDB databases are configured with 4k table spaces).
For Sybase ASE, note the following:
The option 'DDL in tran' should be set to true. You can set this through the Sybase central gui application or with the sp_dboption stored procedure.
The option 'select into' should be set to true. You can set this through the Sybase central gui application or with the sp_dboption stored procedure.
Your database must be configured to support:
SQL Authentication Mode
TCP/IP connections
The agentServiceDB can be shared by multiple agents.
For SQL Server, note the following:
Business Transaction Management requires that the default language associated with a user has a MDY or YMD date format. The simplest way to satisfy this requirement is to use English as the default language. Note that the default language setting does not affect the language of data stored in the database.
SQL Server 2005: The Business Transaction Management performance server uses an outer join syntax that is not supported by default by SQL Server 2005. In order to ensure that the performance server will work correctly with your MS SQL Server 2005 database, please issue the following isql command:
sp_dbcmptlevel @dbname = "performanceDB", @new_cmptlevel = 80
Download the distribution file and unzip it into a directory (referred to as install_dir).
If you haven't already done so, configure the security settings explained in Section 2.1.1, "Configuring security".
In the WebSphere Administrative Console, deploy the following applications (located in install_dir\archives):
Deploy apMain on the central application server in your enterprise environment. This application contains the sphere service, and is deployed once per Business Transaction Management environment. The sphere service manages the entire Business Transaction Management environment.
Deploy apPerformanceServer once on a machine other than the machine on which apMain and apTransactionServer are deployed.
Deploy apTransactionServer once on a machine other than the machine on which apMain and apPerformanceServer are deployed.
Deploy apProxyNode on every application server that hosts business services that you want to place under management with proxy agents (use apContainer if you plan on using plug-in agents only).
Deploy apMonitorNode on every application server where you want to monitor objects other than web services.
Deploy apContainer on every application server where you want to monitor business services with plug-in agents only.
(Optional) Deploy sample applications in a container that is hosting a container service. Sample applications are located in install_dir/samples/applications/WebSphere.
Start the deployments.
Oracle supplies a version of Business Transaction Management that is packaged for single-node installation for demonstration and training purposes. Download and extract AMSJavaDemo.zip, and then deploy apDemo (located in Install_Dir\archives). Next, configure Business Transaction Management as described below, noting that the URLs for the performance transaction servers use the same port and host name as the sphere, and that both servers start when you start the sphere server.
The Business Transaction Management online help is packaged as a web application. Install the online help as follows:
Locate apamshelp.ear in install_dir/archives.
Use the WebSphere deployment tool to deploy apamshelp.ear onto the server where apMain or apDemo is deployed.
Repeat step 2 for the server where apPerformanceServer is deployed.
Note:
You can use the Business Transaction Management Command Line Interface (CLI) to perform a scripted configuration of Business Transaction Management. For first-time configuration, we recommend that you use the browser-based Initial Configuration Wizard, as described below. See Chapter 4, "Scripted configuration of Oracle Business Transaction Management".Point a browser at the server that hosts apMain. Use a URL in the form of:
http://host_name:port_number/apasc
The Business Transaction Management Console appears.
Log in using a set of credentials from the container's administrators group.
Accept the End User License Agreement and click Next.
If you plan to use the Embedded Database, leave this radio button selected as the default and click Next. If you have set up an external database and created the required tables (as described in Section 2.4, "Setting up your Business Transaction Management databases"), select the Enterprise Database radio button and click Next.
(If you are using an enterprise database) Fill out the connection information for the databases you are using for the system services. Be sure to use the same database names as the ones you created when you set up your databases. Note that the information you specify on this screen will carry forward and populate the agent message log database fields in step 7e. Click Next when you complete this screen.
Double-check the default URL for the sphere—in most cases the default should be correct (unless you are running in an HTTPS environment) and you should just click Next.
Typically you install the sphere on the same machine where you install the user interface. If this is not the case, modify the sphere URL appropriately and click Next.
Note:
If you click the Test Sphere URL link and the sphere URL is correct, the system displays a Sphere Status page that indicates that the sphere is uninitialized. This is expected and the sphere service will be initialized at the completion of the configuration. If the URL is incorrect, the browser displays a “page not found” error.Business Transaction Management requires additional credentials to successfully connect to the JMX admin server (available over the SOAP connector). When global security is turned on, the SOAP connector port is available only over SSL (with mutual authentication), and Business Transaction Management requires certain additional settings. Additionally, the Business Transaction Management deployment driver uses the client key stores and trust stores to successfully connect to the SOAP connector port over SSL to query for JMX MBeans. Finally, a deployment manager URL is required to locate the SOAP connector port.
Enter the following information:
User name and password of a user in your application server's Administrators group.
Deployment Manager URL. In a WebSphere Network Deployment (ND) environment, the SOAP connector typically runs in the WebSphere Deployment Manager. Please check the SOAP Connector settings on the Deployment Manager to confirm this and to determine the SOAP connector port. In an ND environment, specify the host on which the Deployment Manager is running and the SOAP connector port of the Deployment Manager. In a non-ND environment (where a SOAP connector runs in each standalone administrative server), specify the host on which the administrative server is running, and the SOAP connector port of the administrative server. If you are running several administrative servers, please use the settings for the administrative server on which apMain is deployed.
Key store location and associated password. This is the key store that the Business Transaction Management deployment service will use to sign its communication with the WAS deployment manager. This is a .jks file local to the Business Transaction Management deployment service that is being added to the sphere (not the Deployment Manager). The location takes the form of:
WAS_install_dir/profiles/your_profile/etc/<client_key_file.jks
Trust Store location and associated password. This is the trust store that the Business Transaction Management deployment service will use to trust the signature of its local WAS deployment manager. This is a .jks file local to the Business Transaction Management deployment service that is being added to the sphere (not the Deployment Manager). The location takes the form of:
WAS_install_dir/profiles/your_profile/etc/client_trust_file.jks
If you are using an embedded database, no database information is required, so click Next. If you are using an enterprise database, check the database information for the agent message log database (it uses the information you specified in step 5), and then click Next.
Enter the URL to the container in which you installed apPerformanceServer (http://hostname:port/apcontainer/container). Make sure that you deploy apPerformanceServer before you exit this screen.
For the WebSphere instance that hosts apPerformanceServer, enter the information described in step 7.
Enter the URL to the container in which you installed apTransactionServer (http://hostname:port/apcontainer/container). Make sure that you deploy apTransactionServer before you exit this screen.
For the WebSphere instance that hosts apTransactionServer, enter the information described in step 7.
View the Summary information and click Finish.
Business Transaction Management validates the information you supplied during configuration, and if all the information checks out, configuration completes successfully and the Business Transaction Management Console appears.
If certain configuration information cannot be validated, Business Transaction Management displays an error message as well as a check box with the following text: “Ignore these errors and proceed with a potentially incompletely configured system.” In general you should attempt to correct the configuration error(s). However, you also have the option of proceeding to a partially configured Business Transaction Management by enabling the checkbox and clicking Finish again. If you choose to access the partially configured system, you will need to correct the configuration errors before you can successfully use the product. For example, if your database connection information was not accurate, you will need to re-configure it from within the Business Transaction Management Console.
For information about configuring databases after initial configuration, refer to the Business Transaction Management online documentation. Navigate to the book “Administering and configuring AMS”, and then the sub-book “Administering Databases”.
Register remote application servers with the sphere.
For each node on which you deployed apContainer, apProxyNode, or apMonitorNode, you must register the application server into which the container service was deployed.
To register an application server:
Navigate to the Network / Infrastructure view in the Business Transaction Management Console.
Select Register > Container and refer to step 7 for details about how to specify information in an ND or non-ND environment. Remember if the container you are registering is part of a non-ND environment, you use the administrative server on which apNode or apContainer is deployed.
Note that Business Transaction Management provides the registerContainer command to support scripted registration of application servers. See the Business Transaction Management online documentation for more information. Navigate to the book Administering and Configuring AMS, and then the sub-book Command Line Utilities/AmberPoint command line interface (CLI).
Repeat for each node that hosts apContainer, apProxyNode or apMonitorNode.