This chapter describes how to install and perform the initial configuration of the Business Transaction Management central servers on the following application servers:
Oracle WebLogic 10.3.2 through 10.3.5
IBM WebSphere 7.0
Ensure that all prerequisite and preliminary setup requirements described in Chapter 4 have been satisfied, including:
Optional – Configure the persistent storage directories (see Configuring Persistent Storage Directories).
Deploy the central servers (see Deploying the Central Servers).
Review the default mapping of users to Business Transaction Management application roles and make adjustments if necessary (see Mapping Users to Business Transaction Management Application Roles).
Perform the initial configuration of Business Transaction Management (see Initial Configuration of Business Transaction Management).
At initial startup, Business Transaction Management creates a set of persistent storage directories to collect system output log entries and store user preferences for the system deployments. By default, the persistent storage directories are created within the application server's installation directory at the following location:
On WebLogic servers:
WL_install_dir/user_projects/domains/domain_name/servers/server_name/btmstorage/*
On WebSphere servers:
WAS_install_dir/profiles/profile_name/btmstorage/node_name/server_name/*
Your company's in-house procedures and rules for persistent storage might require you to place the persistent storage directories in a different location. In such a case, you can reconfigure the location of the persistent storage directories.
An installed Business Transaction Management system is composed of a set of deployments (EAR files), which are themselves composed of subdeployments (WAR files). Each subdeployment has an associated persistent storage directory of the same name, minus the “.war”. The following table lists the names of the deployments, subdeployments, and persistent storage directories.
Table 5-1 Business Transaction Management deployments, subdeployments, and persistent storage directories
| Deployments (EARs) | Subdeployments (WARs) | Persistent storage directories |
|---|---|---|
|
btmMain |
btmui btmcentral btmcontainer |
btmui btmcentral btmcontainer |
|
btmPerformanceServer |
btmcontainer btmperformance |
btmcontainer btmperformance |
|
btmTransactionServer |
btmcontainer btmtransaction |
btmcontainer btmtransaction |
|
btmMonitor |
btmmonitor |
btmmonitor |
Create the persistent storage directories in your file system, in the location that you want them.
You must name the directories using the default names, as listed in Table 5-1. Leave the directories empty.
Locate the distribution archive for the Business Transaction Management central servers and unzip it into a directory.
The distribution archive is named BTM_MonitorServices*.zip, where * represents the version number. This archive also contains the Business Transaction Management monitor.
Modify the persistent storage directory location as specified in each subdeployment's web.xml file:
Locate and expand the WAR file for the deployment whose storage directory location you want to change.
Within the expanded WAR file, open the WEB-INF/web.xml file in a text or XML editor.
Set the new location for the storage directory by editing the value of the storageDirectory parameter:
As shown in the following example, the default value of the parameter is AmberPointDefault:
<!-- PERSISTENT STORAGE DIRECTORY
To set the persistent storage area to some value, change the value of param-value to some EXISTING directory where you want things stored.
-->
<context-param>
<param-name>com.amberpoint.storageDirectory</param-name>
<param-value>AmberPointDefault</param-value>
</context-param>
Delete the value AmberPointDefault and replace it with the path to the storage directory you created, as shown in the following examples:
On Windows systems – If you want the persistent storage directory for btmcentral to be C:\btm_data\btmcentral, change the default entry within your btmcentral web.xml file to the following:
<context-param> <param-name>com.amberpoint.storageDirectory</param-name> <param-value>C:\btm_data\btmcentral</param-value> </context-param>
On Unix-like systems – If you want the persistent storage directory for btmcentral to be opt/webserviceapplogs/btm_data/btmcentral, change the default entry within your btmcentral web.xml file to the following:
<context-param> <param-name>com.amberpoint.storageDirectory</param-name> <param-value>/opt/webserviceapplogs/btm_data/btmcentral</param-value> </context-param>
Repeat this step for each persistent storage directory whose location you want to reconfigure.
Note:
If you are going to reconfigure the location of persistent storage directories for your monitors (as well as for your central servers), this might be a convenient time to do that.Repackage your WAR and EAR files.
You should document the location of your persistent storage directories because when you upgrade or reinstall the central servers, you will need to once again define the location of your persistent storage directories for these deployments.
Note:
These instructions assume that if you are installing onto WebLogic servers, you are using managed instances of WebLogic.Locate the distribution archive for the Business Transaction Management central servers and unzip it into a directory (henceforth referred to as Install_Dir).
The distribution archive is named BTM_MonitorServices*.zip, where * represents the version number. This archive also contains the Business Transaction Management monitor.
Note:
If you configured the persistent storage directories, as described in Configuring Persistent Storage Directories, you will have already completed this step.Optional security step for UNIX-like operating systems – If you want to set file permissions on the files that make up the distribution to the most restrictive level that still maintains functionality, complete this step:
Locate setPermissions.sh at the top level of Install_Dir.
This script contains commands for setting file permissions of all regular files to Owner – read/delete; all directories to Owner – read/execute/delete; and all scripts to Owner – read/execute/delete.
Note:
These permission levels are extremely restrictive. For example, only the owner can read the files.On a command line, at the top level of Install_Dir, run this command:
source setPermissions.sh
This command runs the commands in the script file and sets permissions for all files and directories in the expanded archive.
Using your application server's administration console, deploy each of the following applications (located in Install_Dir\archives):
btmMain
btmPerformanceServer
btmTransactionServer
Deploy only one instance of each of these servers, and for performance considerations you should deploy each to a separate application server instance. You must not deploy any of these servers to an application server instance that hosts services or components you intend to monitor. For more information about the central server applications, see Chapter 1, "Architecture."
For WebLogic – Start all managed servers where you deployed Business Transaction Management components.
Start the deployments.
If you reconfigured the locations of your persistent storage directories (as described in Configuring Persistent Storage Directories), confirm that system output log entries have been written in the new locations.
If this is a reinstallation of the central servers, notify all Business Transaction Management users to flush their web browser caches.
The Management Console contains a number of Adobe Flash widgets. Web browsers normally cache these widgets and will continue to use the older cached widgets until you either flush the cache or restart your web browser.
This section describes Business Transaction Management application roles and the default mappings of Business Transaction Management users to these roles. If necessary, you can reconfigure these mappings using your system administration facilities.
Business Transaction Management applications (the central servers and monitors) rely on the application server in which they are deployed for the authentication of users and the association of application roles with users.
By default, authentication is enabled for the Management Console. If you want to disable authentication, use whatever tool or procedure is appropriate for the application server you are using. If you disable authentication, users of the Management Console must still log in. However, they can log in using any user name and are not required to provide a password. Note that all UI personalizations, such as edits to the Navigator, filters, and column sets are stored as preferences and associated with the user name.
The Business Transaction Management Console uses roles to authorize access to various features of the user interface. In order to log into the Management Console, you must use credentials that are mapped to at least one of theses BTM application user roles: btmAdmin, btmUser, or btmObserver. In order to perform the initial configuration of Business Transaction Management, explained in Initial Configuration of Business Transaction Management, you must log in as a user with the btmAdmin role.
Each Business Transaction Management user must be assigned at least one primary role. The primary roles are:
btmAdmin – Users with this role are granted all privileges. These users can use all tools and facilities provided by the Management Console, including the ability to view and create sensitive properties and to view all message content.
btmUser – Users with this role have most privileges needed to configure basic monitoring. For example, they can configure monitors; create, edit, and delete policies (does not include system policies); register services; set registry attributes on services and endpoints; and create and edit transactions and conditions. They also have all the privileges of btmObserver. This role does not grant the privilege to modify the Business Transaction Management environment, access message content, or view or edit sensitive properties.
btmObserver – Users with this role have privileges to use most of the basic monitoring facilities. They can view summary, dependency, and administrative information about the monitoring system, but are not allowed to configure any of the policies or settings related to it. They can also view transactions and conditions, but are not allowed to create or edit them. This role does not allow users to modify the Business Transaction Management environment, access message content, or view or edit sensitive properties.
Note:
All navigation and views in the Management Console are available to all primary roles. However, some roles cannot access certain menus and menu items and the tools associated with them.In addition to the primary roles, Business Transaction Management defines an auxiliary role. The auxiliary role provides additional privileges that you might want to assign certain users. For example, you might want to let a user access message content but not want to give that user full administrative privileges. You could do this by assigning the user a primary role of btmUser and an auxiliary role of btmInspector. The auxiliary role is:
btmInspector – Users with this role can view message content and view and create properties, including sensitive properties.
Note:
The btmAdmin role has all of the privileges of btmInspector.In a WebLogic server, the role of Business Transaction Management administrator (btmAdmin) is automatically mapped to the Administrators group defined in your WebLogic server. The role of Business Transaction Management user (btmUser) is mapped to the groups Operators and Monitors. The role of Business Transaction Management observer (btmObserver) is mapped to the group Everyone, granting all authenticated users observer privileges. The following table lists the Business Transaction Management application roles and their default mappings to application server groups:
Table 5-2 Role Mapping in WebLogic
| Business Transaction Management Application Role | Application Server Group |
|---|---|
|
btmAdmin |
Administrators |
|
btmUser |
Operators, Monitors |
|
btmObserver |
Everyone |
|
btmInspector |
btmInspectors |
Note:
The role btmInspector is, by default, mapped to a group named btmInspectors, but the application server administrator must create a group named btmInspectors and assign it to the appropriate users.You can modify these default mappings in the WebLogic deployment descriptor file (weblogic.xml).
In a WebSphere server, the application role of Business Transaction Management administrator (btmAdmin) is automatically mapped to the Administrators group on Windows systems, or the adm, sys, and bin groups on Unix-like systems. The roles of Business Transaction Management user (btmUser) and observer (btmObserver) are mapped to all authenticated users on your system. The following table lists the Business Transaction Management application roles and their default mappings to your operating system groups:
Table 5-3 Role Mapping in WebSphere
| Business Transaction Management Application Role | Operating System Group |
|---|---|
|
btmAdmin |
Administrators (Windows); adm, sys, and bin (Unix-like systems) |
|
btmUser, btmObserver |
all authenticated users |
|
btmInspector |
btmInspectors |
Note:
The role btmInspector is, by default, mapped to a group named btmInspectors, but the application server administrator must create a group named btmInspectors and assign it to the appropriate users.These initial mappings assume that WebSphere security is configured to use Local OS Registry. If you are using a different security setup, you might have to remap users/groups based on your authentication domain settings.
You can change these mappings in the WebSphere Administrative Console, on the “Mapping Users to Roles” page. If you change the mappings, you should change them for all BTM applications. The names of all BTM applications (EAR files) begin with the string “btm”.
Before you can access the facilities of Business Transaction Management, you must perform an initial configuration of the central servers. If this is the first time you have installed Business Transaction Management, you should use the browser-based Configuration wizard, as described below. However, for subsequent installations, you might want to use the Command Line Interface (CLI) to perform a scripted configuration of Business Transaction Management. For more information, see "Scripted Configuration of Oracle Business Transaction Management".
Ensure that the central servers are running.
Open the Management Console by pointing a web browser at the server that hosts the btmMain deployment.
Use a URL in the form of:
http://host_name:port_number/btmui
The Management Console login page opens.
Log in as a user that is in the btmAdmin role (see Mapping Users to Business Transaction Management Application Roles for information about this role).
The introductory page of the Configuration wizard opens.
Click Next, and the Database Type page opens.
Choose External Database (the embedded database is not supported for production systems).
When finished, click Next, and the External Database Configuration page opens.
Provide the connection string to your Oracle instance and the user names and passwords for the database users you created in Setting up Business Transaction Management Databases.
If you created the users on separate Oracle instances, first select Custom so that you can provide multiple connection strings. If you are using a single connection string for all databases, each database requires a distinct user name.
When finished, click Next, and the Sphere URL page opens.
Ensure that the URL for the sphere is correct—in most cases the default should be correct (unless you are running in an HTTPS environment).
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 not initialized. 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.When finished, click Next, and the Local Container Setup page opens.
This page lets you optionally specify DNS aliases for the network node on which you installed btmMain.
The use of aliases helps avoid the creation of duplicate endpoints when users register services manually or when the system observes message traffic at an alias address. Use a comma to separate multiple addresses.
When finished, click Next, and the Performance Monitoring Components page opens.
Enter the URL at which you deployed btmPerformanceServer in the form of http://HostName:Port/btmcontainer/container/.
This URL must end with “/btmcontainer/container/”. Make sure that you deploy apPerformanceServer before you exit this screen.
When finished, click Next, and the Local Container Setup page opens again (unless you deployed btmPerformanceServer to the same machine as btmMain).
This page lets you optionally specify DNS aliases for the network node on which you installed btmPerformanceServer.
When finished, click Next, and the Transaction Monitoring Components page opens.
Enter the URL at which you deployed btmTransactionServer in the form http://HostName:Port/btmcontainer/container/.
This URL must end with “/btmcontainer/container/”. Make sure that you deploy btmTransactionServer before you exit this screen.
When finished, click Next, and the Local Container Setup page opens again (unless you deployed btmTransactionServer to the same machine as btmPerformanceServer or btmMain).
This page lets you specify DNS aliases for the network node on which you installed btmTransactionServer.
When finished, click Next, and the Summary of Configuration page opens.
Ensure that the configuration information is correct and click Finish.
Business Transaction Management validates the information you supplied during configuration, and if all the information is valid, configuration completes successfully and the Business Transaction Management Console appears.
If any 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 any configuration errors. However, you have the option of proceeding with Business Transaction Management partially configured 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 help.