| Oracle® Business Transaction Management Installation Guide for WebLogic Server Release 6.5 E18070-01 |
|
 Previous |
 Next |
| Oracle® Business Transaction Management Installation Guide for WebLogic Server Release 6.5 E18070-01 |
|
Previous |
Next |
This chapter describes how to install and configure Business Transaction Management on Oracle WebLogic.
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 WebLogic 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 WebLogic 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=="
|
Note: If you are using a WebLogic Node Manager, you will use the WebLogic Administrative Console to adjust settings rather than edit scripts. |
If you are using an external database, add the appropriate database driver to the WebLogic CLASSPATH.
Add ap-mto-runtime.jar into your WebLogic CLASSPATH of every server that hosts a container service (servers hosting apMain, apContainer, apMonitorNode, or apProxyNode). This JAR file is located in install_dir/archives. Note that if you do not install ap-mtoruntime.jar on the server running apMain, several Business Transaction Management system services will be displayed as degraded in the Business Transaction Management Console.
To add the JAR file to your CLASSPATH, edit WebLogic_install_dir\user_projects\domains\domainName\bin\startWebLogic.cmd. If you perform this edit while the server is running, be sure to restart WebLogic before configuring BTM.
|
Note: If you point to the JAR files in the archives directory, be sure this directory does not get deleted. |
Increase the server memory by opening your domain's setDomainEnv.cmd file in a text editor and editing the following settings (note these are minimum recommendations; the setDomainEnv.cmd file is located in your domain's bin directory):
MEM_ARGS=-Xms256m -Xmx768m (There is one entry for this.)
-XX:MaxPermSize=256m (There are several entries for this; edit them all.)
In the domain in which you will install Business Transaction Management, ensure that the listen address property for the Business Transaction Management domain is set to a valid host name. By default, this property is empty, which defaults to 127.0.0.1. Do not leave this field empty.
Set up an administrative user.
Business Transaction Management maps roles defined in WebLogic to its own application roles. See Chapter 2, "Mapping Users to Business Transaction Management Application Roles".
The 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.
Business Transaction Management applications rely on the WebLogic container for authentication and association of roles with users. The roles of Business Transaction Management administrator (amfadmin, slmadmin, exmadmin) are automatically mapped to the Administrators group defined in your WebLogic server. The roles of Management Console user (amfuser, slmuser, exmuser) are mapped to the groups Operators and Monitors. The roles of Business Transaction Management observer (amfobserver, slmobserver, exmobserver) are mapped to the group Everyone, granting all authenticated users observer privileges. The following table lists the Business Transaction Management application roles and their default container role mapping:
Table 2-1 Role Mapping in WebLogic
| Business Transaction Management Application Roles | Container Group |
|---|---|
|
amfadmin exmadmin slmadmin |
Administrators |
|
amfuser exmuser slmuser |
Operators, Monitors |
|
amfobserver exmobserver slmobserver amf_limited_observer exm_limited_observer slm_limited_observer amf_proxy_user exm_proxy_user slm_proxy_user |
Everyone |
|
exm_inspector |
exm_inspector |
You can modify these default mappings in the WebLogic deployment descriptor file (weblogic.xml). For more information on setting up user accounts and assigning roles, see the “Authentication and Role Mapping” topic of the Business Transaction Management online help.
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
|
Note: These instructions assume you are using managed instances of WebLogic. |
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 the section “Configuring security” on page 6.
If you haven't already done so, download Current.license.xml and place it in a temporary directory.
In the WebLogic Administrative Console, deploy the following applications (located in install_dir\archives):
Deploy apContainer on the Admin Server.
Deploy apMain on a Managed Server that will act as the central application server (take all the defaults).
Deploy apPerformanceServer once on a machine other than the machine on which apMain is deployed. This application contains the service-level management components.
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 only plug-in agents).
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 managed server instance that is hosting a container service. Sample applications are located in install_dir\samples\applications\WebLogic9.
Start all managed servers where you installed apContainer, apProxyNode, or apMonitorNode, including the Admin server.
Start the deployments.
Oracle supplies a version of Business Transaction Management that is packaged for single-node installation. This packaging of the product is intended for demonstration and training purposes, only. 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 WebLogic 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 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 9. 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. |
Enter the credentials of a user in your application server's Administrators group.
If you are using an embedded database, no database information is required, so click Next.
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://host_name:port/apcontainer/container). Make sure that you deploy apPerformanceServer before you exit this screen.
Enter a set of credentials of a user in the Administrator's group of the application server instance in which apPerformanceServer is deployed.
Enter the URL to the container in which you installed apTransactionServer (http://host_name:port/apcontainer/container). Make sure that you deploy apTransactionServer before you exit this screen.
Enter a set of credentials of a user in the Administrator's group of the application server instance in which apTransactionServer is deployed.
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 any configuration information cannot be validated, the following message is displayed: “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. 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 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 Management Console.
Select Register > Container and refer to the online help if you need more information.
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.
