Skip Headers
Oracle® Business Transaction Management Installation Guide
12.1.0.3

E37016-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

6 Installing and Configuring the Central Servers

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.

Overview of Installing and Configuring the Central Servers

  1. 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").

  2. Ensure that all prerequisite requirements and setup described in Chapter 5 are satisfied, including:

  3. Optional – Configure the persistent storage directories (see Configuring Persistent Storage Directories).

  4. Deploy the central servers (see Deploying the Central Servers).

  5. Review the default mapping of users to Business Transaction Management application roles and make adjustments if necessary (see Mapping Users to Roles).

  6. Perform the initial configuration of Business Transaction Management (see Initial Configuration of Business Transaction Management).

  7. Configure the location of your Enterprise Manager server (see Configuring the Connection to Enterprise Manager).

Configuring Persistent Storage Directories

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.

Table 6-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


Reconfiguring the Location of Persistent Storage Directories

  1. 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.

  2. 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.

  3. Modify the persistent storage directory location as specified in each subdeployment's web.xml file:

    1. Locate and expand the WAR file for the deployment whose storage directory location you want to change.

    2. Within the expanded WAR file, open the WEB-INF/web.xml file in a text or XML editor.

    3. 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>
      
    4. 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.
  4. 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.

Deploying the Central Servers

Note:

These instructions assume that if you are installing onto WebLogic servers, you are using managed instances of WebLogic.
  1. 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.
  2. 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:

    1. 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.
    2. 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.

  3. 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."

  4. Start all managed servers where you deployed Business Transaction Management components.

  5. Start the deployments.

  6. 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.

  7. 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.

Mapping Users to Roles

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.

Business Transaction Management Application Roles

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.

Primary Roles

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.

Auxiliary Role

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.

Mapping WebLogic Users to Business Transaction Management Roles

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 6-2 Role Mapping in WebLogic

Business Transaction Management Application Role Application Server Group

btmAdmin

Administrators

btmUser

Operators, Monitors

btmObserver

Everyone

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.

Initial Configuration of Business Transaction Management

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".

  1. Ensure that the central servers are running.

  2. 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.

  3. Log in as a user that is in the btmAdmin role (see Mapping Users to Roles for information about this role).

  4. The introductory page of the Configuration wizard opens.

    Click Next, and the Database Type page opens.

  5. Choose External Database (the embedded database is not supported for production systems).

    When finished, click Next, and the External Database Configuration page opens.

  6. 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.

  7. 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.

  8. 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.

  9. 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).

  10. 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.

  11. 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).

  12. 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.

  13. 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.

Configuring the Connection to Enterprise Manager

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:

  1. Open the Business Transaction Management console.

  2. In the Navigator, select Administration > System Services.

  3. In the main area, select AP_Sphere_Service.

  4. From the menu bar, choose Admin > Edit Setup Data for AP_Sphere_Service.

  5. Click the Edit XML button.

    The sphere services setup XML file is displayed.

  6. Scroll to the bottom of the file and locate the <pfx6:emgcURL/> element.

  7. Add the base URL of your Enterprise Manager server as the value of this element, for example:

    <pfx6:emgcURL>https://myEMhost:5416/</pfx6:emgcURL>
    

    Note:

    The namespace prefix might be other than pfx6; use whatever value appears in the XML text.
  8. Directly following the <pfx6:emgcURL/> element, locate the <pfx6:SphereSetupDataVersion/> element.

  9. 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:

      jdbc:oracle:thin:@myhost.mydomain.com:15044:mySID
      
  10. Click the Apply button.