This chapter describes how to install and perform the initial configuration of the Business Transaction Management central servers on Oracle WebLogic 10.3.2 through 10.3.5.
Optional – Configure security for the central servers. You can also perform the security configuration for the monitors and observers at this time, if you wish (see Chapter 4, "Configuring Security").
Ensure that all prerequisite requirements and setup described in Chapter 5 are 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 Roles).
Perform the initial configuration of Business Transaction Management (see Initial Configuration of Business Transaction Management).
Configure the location of your Enterprise Manager server (see Configuring the Connection to Enterprise Manager).
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 WL_install_dir/user_projects/domains/domain_name/servers/server_name/btmstorage/*.
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.
|Deployments (EARs)||Subdeployments (WARs)||Persistent storage directories|
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 6-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_Servers*.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_Servers*.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:
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):
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."
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:
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:
|Business Transaction Management Application Role||Application Server Group|
btmInspector (Note that this is singular.)
btmInspectors (Note that this is plural.)
Note:By default, the role btmInspector is mapped to a group named btmInspectors. Because this group does not exist by default, the application server administrator must create the group and assign it to the appropriate users.
You can modify these default mappings in the WebLogic deployment descriptor file (weblogic.xml). If you change the mappings, you should change them for all Business Transaction Management applications. The names of the applications (EAR files) begin with the string “btm”. Refer to your WebLogic documentation for further information about editing the default mappings.
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:
The Management Console login page opens.
Log in as a user that is in the btmAdmin role (see Mapping Users to Roles for information about this role).
The introductory page of the Configuration wizard opens.
Click Next, and the Database Type page opens.
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.
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.
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.
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.
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.
If you have Oracle Enterprise Manager installed, perform the configuration procedure described in this section so that Business Transaction Management can connect to your Enterprise Manager installation. During this procedure you will:
Provide the location of your Enterprise Manager server.
This information enables Business Transaction Management to locate your Java Virtual Machine Diagnostics server, which in turn enables you to drill down from various places in the Business Transaction Management UI into the Java Virtual Machine Diagnostics UI.
If you don't provide this information or provide the wrong information, you will receive an error message when you attempt to drill down into the Java Virtual Machine Diagnostics UI.
Even though you might not have Java Virtual Machine Diagnostics currently installed, you should perform this step of the procedure in case you decide to install it later on.
Provide the connection string and user credentials for accessing the Enterprise Manager repository.
This information enables Business Transaction Management to send transaction-related SLA events to Enterprise Manager, where they are displayed as events or incidents. Note that you must also associate the transaction with a business application target in Enterprise Manager for the events to be displayed. For information about associating transactions with business application targets, refer to the Business Transaction Management online help after you finish installing the product.
Open the Business Transaction Management console.
In the Navigator, select Administration > System Services.
In the main area, select AP_Sphere_Service.
From the menu bar, choose Admin > Edit Setup Data for AP_Sphere_Service.
Click the Edit XML button.
The sphere services setup XML file is displayed.
Scroll to the bottom of the file and locate the <pfx6:emgcURL/> element.
Add the base URL of your Enterprise Manager server as the value of this element, for example:
Note:The namespace prefix might be other than pfx6; use whatever value appears in the XML text.
Directly following the <pfx6:emgcURL/> element, locate the <pfx6:SphereSetupDataVersion/> element.
Replace the <pfx6:SphereSetupDataVersion/> element with the following code:
<pfx6:SphereSetupDataVersion> <pfx6:emgcRepos> <pfx1:User>myUserName</pfx1:User> <pfx1:Password>myPassword</pfx1:Password> <pfx1:Driver>oracle.jdbc.OracleDriver</pfx1:Driver> <pfx1:Connection>myDatabaseConnectionString</pfx1:Connection> <pfx1:DatabaseConnectionVersion/> </pfx6:emgcRepos> <pfx6:SphereSetupDataVersion/> </pfx6:SphereSetupDataVersion>
In this code, replace:
myUserName and myPassword with the username and password of an account that has privilege to access your Enterprise Manager repository.
myDatabaseConnectionString with the connection string to your Enterprise Manager Repository, for example:
Click the Apply button.