Oracle Discoverer 4i Configuration Guide for Oracle9i Application Server Release 4.1 for UNIX A87572-01 |
Library | Service | Contents | Index

# 3
Installing Oracle Discoverer 4i on multiple machines

Oracle Discoverer 4i Plus and Oracle Discoverer 4iViewer are automatically installed to run with Oracle9i Application Server as a single machine installation. However Oracle Discoverer 4i is designed to be deployed on multiple machines. The Discoverer Services can be replicated by specifying the machines available to Discoverer in a configuration file. Discoverer Services sessions are then started on alternate machines to balance the load.

In this way very large numbers of Discoverer users can be supported, since there is no single bottleneck. Multiple Discoverer sessions can run on a single machine, or can be spread across multiple machines as required.

The topics include:

- What are the differences between a default installation and a distributed installation of Oracle Discoverer 4i?

- Performing a distributed installation

## 3.1 What are the differences between a default installation and a distributed installation of Oracle Discoverer 4i?

### 3.1.1 Default Installation of Oracle Discoverer 4i

Oracle Discoverer 4i is installed as part of Oracle9i Application Server. The default installation is a single machine installation (i.e. all the Discoverer components are installed on a single machine).

In this scenario, the Oracle 9i Application Server installation has installed both of the following on the same machine:

- HTTP Server software

- all the Discoverer Services components (Locator, Session, Preferences, SmartAgent, and Object Activation Daemon)

The machine is therefore both an HTTP Server machine and an Application Server machine.

When a user launches a web browser on a client machine to start Discoverer 4i, the web browser sends a request to the HTTP Server software on the server machine. That request is processed and a Discoverer session is started on the server machine.

### 3.1.2 Distributed Discoverer 4i Installation

Having a single machine acting as both the HTTP Server machine and the Application Server machine can be inefficient when supporting large numbers of Discoverer users.

For this reason, the Discoverer Services components are designed to be deployed on multiple machines. By specifying the available machines in a configuration file, Discoverer Services sessions can be started on different machines to balance the load. Multiple Discoverer sessions can run on a single machine, or can be spread across multiple machines as required.

In this scenario (as with a default installation), the Oracle 9i Application Server installation has installed both of the following on the same machine:

- HTTP Server software

- all the Discoverer Services components (Locator, Session, Preferences, SmartAgent, and Object Activation Daemon)

The machine is therefore both an HTTP Server machine and an Application Server machine. This machine is referred to as the Master Discoverer Server machine.

As well as creating a Master Discoverer Server, you also install the Oracle 9i Application Server on additional machines. These machines are referred to as Additional Discoverer Server machines.

When a user launches a web browser on a client machine to start Discoverer 4i, the web browser sends a request to the HTTP Server software on the Master Discoverer Server machine. That request is processed and a Discoverer session is started either on the Master Discoverer Server machine or on an Additional Discoverer Server machine.

Each Additional Discoverer Server machine can run multiple sessions; therefore, the number of machines you choose to use for sessions depends on how many concurrent sessions the users need, the amount of memory available, the speed of the hardware, and so forth.

## 3.2 Performing a distributed installation

### 3.2.1 Confirming connection to the default Master Discoverer Server machine

Before you start altering the default installation, we recommend that you connect to the default Master Discoverer Server machine to confirm that the default installation is functioning correctly.

1. Start a Web browser on a client machine.

2. Connect to the default Master Discoverer Server by typing the following URL:

       http://hostname.domain/discoverer4i/viewer

   where hostname.domain is the fully qualified name of the machine on which Oracle9i Application Server has been installed.

   The Oracle Discoverer 4i Viewer login screen appears when the default installation is functioning correctly.

### 3.2.2 Confirming the name of the Master Discoverer Server machine

During installation, the machine name is used as the Master Discoverer Server instance name. Make a note of the name of the Master Discoverer Server machine now because you will need it when installing on the machines that will become Additional Discoverer Server machines.

If you are not sure of the Master Discoverer Server machine name, follow the instructions below:

1. Use a text editor to open the htmlvars.js file in the following location:

   <iSUITES_HOME>/Apache/Apache/htdocs/discwb4/scripts

2. Look for the string ORAWEBDISCO_INSTANCE.

   The value of this string is the Master Discoverer Server machine name (and therefore the Master Discoverer Server instance name).

### 3.2.3 Installing Oracle Discoverer on Additional Discoverer Server machines

On every machine that you want to make an Additional Discoverer Server machine:

1. Follow the instructions in the Oracle9i Application Server Installation Guide to install Oracle9i Application Server on the machine you want to use as the Additional Discoverer Server machine.

2. On the Additional Discoverer Server machine, navigate to the <ORACLE_806_HOME>/DISCWB4 directory and set the Discoverer environment variables by running the appropriate script:

   - If you are using the Korn shell or the Bourne shell, type the following at the command prompt:

         > . ./discwb.sh

     Note that you must separate the periods with a space

   - If you are using the C shell, type the following at the command prompt:

         > source discwb.csh

3. On the Additional Discoverer Server machine, navigate to the <ORACLE_806_HOME>/DISCWB4/util directory and type the following at the command prompt to unregister the corresponding Discoverer components:

       > unregistersession.sh

       > unregistercollector.sh

       > unregisterpreference.sh

4. On the Additional Discoverer Server machine, navigate to the <ORACLE_806_HOME>/DISCWB4/util directory and type the following at the command prompt to stop all Discoverer processes:

       > stopall.sh

5. On the Additional Discoverer Server machine, delete the following scripts from the <ORACLE_806_HOME>/DISCWB4/util directory:

   - registerpreference.sh

   - registercollector.sh

   - startlocator.sh

   - unregisterpreference.sh

   - unregistercollector.sh

6. On the Additional Discoverer Server machine, use a text editor to open the registersession.sh file and replace the Additional Discoverer Server machine name with the name of the Master Discoverer Server machine.

   Note that there are three occurrences of the Additional Discoverer Server machine name in the registersession.sh file:

   - two occurrences of the Additional Discoverer Server machine name are prepended to the string OracleDiscovererSession4

   - one occurrence of the Additional Discoverer Server machine name is prepended to the string OracleDiscovererPreferences4

7. On the Additional Discoverer Server machine, use a text editor to open the unregistersession.sh file and replace the Additional Discoverer Server machine name with the name of the Master Discoverer Server machine.

   Note that there is one occurrence of the Additional Discoverer Server machine name in the unregistersession.sh file (prepended to the string OracleDiscovererSession4).

8. On the Additional Discoverer Server machine, navigate to the <ORACLE_806_HOME>/DISCWB4/util directory and type the following at the command prompt to start the OAD and Session component:

       > startoad.sh

       > startosagent.sh

       > registersession.sh

When you have installed Oracle Discoverer on every machine that you want to be an Additional Discoverer Server machine, you must:

- edit the pref.txt file on the Master Discoverer Server machine (Discoverer Plus and Viewer - see Section 3.2.4)

- edit the tnsnames.ora file on all Discoverer Server machines (Discoverer Plus and Viewer - see Section 3.2.5)

- edit the disco4iv.xml file on the Master Discoverer Server machine (Discoverer Viewer only - see Section 3.2.6)

### 3.2.4 Editing the Discoverer Services pref.txt file (Discoverer Plus and Viewer)

#### 3.2.4.1 What is the pref.txt file?

The pref.txt file located on the Master Discoverer Server machine contains a number of default settings that apply to all end users.

The only information required in the pref.txt file is the IP addresses (or machine names) of the machines used for Discoverer 4i. The other items in the pref.txt file can be edited to suit your network or user requirements. See Section 3.2.4.5, "How to edit the pref.txt file" for more information.

A backup copy of pref.txt is located at <ORACLE_806_HOME>/DISCWB4/util/defaults.txt on the Master Discoverer Server machine. If you make a mistake when editing, lose, or corrupt the pref.txt file, you can restore the file to its default values from the backup copy.

#### 3.2.4.2 Why edit the pref.txt file?

In a distributed Discoverer installation, the pref.txt file located on the Master Discoverer Server must contain either the IP address or machine name of each Application Server machine that will run Discoverer 4i sessions.

The order of the IP addresses listed in the pref.txt file determines the order in which sessions are started on each machine that has a Session component installed. Editing the pref.txt file enables you to add Additional Discoverer Server machines and to balance the load between them.

Entries in the pref.txt file are comma space delimited (i.e. entries are separated by a comma followed by a space). Enclose the entries in "double quotes."

Note: Using IP addresses is somewhat faster because using machine names requires one extra lookup. See your System administrator for details about using IP addresses versus machine names.

#### 3.2.4.3 What is load balancing?

Load balancing is a way to improve the performance of your Discoverer installation by distributing sessions amongst different machines to make the most efficient use of each machine. You specify the machines to use by including their IP addresses (or machine names) in the pref.txt file.

The Discoverer Services Locator component uses the list of machines in the pref.txt file to determine which machine starts the next requested session. Using a round-robin method, the Locator requests a session on each machine in order, until it reaches the end of the list of IP addresses. When the Locator reaches the end of the list, it returns to the beginning of the list and starts over.

This round-robin method enables you to balance the load placed on the machines by:

- listing the machines in a particular order

- including the same machine several times

For example, you may want one machine to handle five sessions before the next machine is used. If so, include the first machine's IP address five times before including the next machine's address in the pref.txt file

Load balancing can greatly affect performance. We recommend that you plan a load balancing strategy before editing the pref.txt file. Consider the speed and performance of each server machine. For planning purposes, you can estimate that each session requires approximately 8 to 12 MB of memory.

#### 3.2.4.4 Examples of Load Balancing

Example 1: Load balancing - equal machines

You have Discoverer Session components installed on two Application Server machines. Each machine has the same processor speed and RAM. The IP addresses for these two machines are:

##### Table 3-1 Sample Server Names

Server | Machine Name | IP address
--- | --- | ---
App Server machine 1 | disco1 | 123.456.789.1
App Server machine 2 | disco2 | 123.456.789.2

You want App Server machine 1 to handle the first request, App Server machine 2 to handle the next, App Server machine 1 the next, and so on.

The pref.txt file entry would look like this:

Machine IPs="disco1, disco2"

or

Machine IPs="123.456.789.1, 123.456.789.2"

Example 2: Load balancing - one fast machine plus two other machines

You have Discoverer Sessions installed on three Application Server machines. The first Application Server machine has faster processors and more RAM. The second and third Application server machines are equal to each other in processor speed and RAM.

The IP addresses for these three machines are:

##### Table 3-2 Sample Server Names

Server | Machine Name | IP address
--- | --- | ---
App Server machine 1 | server1 | 123.456.789.1
App Server machine 2 | server2 | 123.456.789.2
App Server machine 3 | server3 | 123.456.789.3

You want App Server machine 1 to handle the first three requests, App Server machine 2 to handle next one, App Server machine 3 the next one, then back to App Server machine 1 for the next three requests.

The pref.txt file entry would look like this:

Machine IPs="server1, server1, server1, server2, server3"

or

Machine IPs="123.456.789.1, 123.456.789.1, 123.456.789.1, 123.456.789.2, 123.456.789.3"

#### 3.2.4.5 How to edit the pref.txt file

You edit the pref.txt file on the machine where you installed the Preferences component (i.e. the Master Discoverer Server machine):

1. Use a text editor to open the pref.txt file in the following location:

   <ORACLE_806_HOME>/DISCWB4/util

2. Type the IP address or machine name for each machine at the line labeled MachineIPs near the top of the file.

3. Separate each IP address or machine name with a comma followed by a space and enclose the entire list in "double quotes."

   For example: "server1, server2, server3".

4. When you're finished editing the pref.txt file, save it and exit.

   For the changes you have made to pref.txt to take effect, you must apply preferences.

5. From the command prompt, navigate to the <ORACLE_806_HOME>/DISCWB4/util directory and run the following script to apply the preferences:

       > ./applypreferences.sh

   If errors are detected in the pref.txt file, the confirmation window file includes an instruction to check the error.txt file. Correct any errors listed in the error.txt file and reapply preferences before continuing.

The preferences are updated and set for the Discoverer Server Instance.

### 3.2.5 Editing the tnsnames.ora file (Discoverer Plus and Viewer)

#### 3.2.5.1 What is the tnsnames.ora file?

The tnsnames.ora file contains the names and aliases of all the databases that users can access using Discoverer 4i or any other Oracle product.

#### 3.2.5.2 Why edit the tnsnames.ora file?

Each server machine in a distributed Discoverer installation must have an identical tnsnames.ora file.

If you have installed Discoverer on an Additional Discoverer Server machine, you must make sure the tnsnames.ora files on the different machines are identical by doing one of the following

- copy the tnsnames.ora file from the Master Discoverer Server machine to each Additional Discoverer Server machine

- edit the tnsnames.ora file on each Additional Discoverer Server so that it is identical to the tnsnames.ora file on the Master Discoverer Server machine

Note that several versions of the tnsnames.ora file might exist on the same machine. It is very important that you copy or edit the correct file.

#### 3.2.5.3 How to copy the tnsnames.ora file

1. Copy the tnsnames.ora file from the following location on the Master Discoverer Server machine to the same location on the Additional Discoverer Server machine and replacing the existing file:

   <ORACLE_806_HOME>/network/admin

   where <ORACLE_806_HOME> is the location in which the Oracle Discoverer Components are installed.

   You can copy the tnsnames.ora file in a number of different ways. For example, you could copy the file having mounted the Master Discoverer Server machine on the Additional Discoverer Server machine as a network drive (e.g using NFS). Alternatively, you could use FTP software to copy the file.

#### 3.2.5.4 How to edit the tnsnames.ora file

One way to edit the tnsnames.ora file:

1. Navigate to the <ORACLE_806_HOME>/DISCWB4 directory and set the Discoverer environment variables by running the appropriate script:

   - If you are using the Bourne shell or the Korn shell, type the following at the command prompt:

         > . ./discwb.sh

     Note that you must separate the periods with a space

   - If you are using the C shell, type the following at the command prompt:

         > source discwb.csh

2. Navigate to the <ORACLE_806_HOME>/bin directory and type the following at the command prompt:

       > net8wiz.sh

   A program runs, enabling you to edit the Net8 configuration.

   To make sure that you edit the correct tnsnames.ora file, do not use the Net8 Configuration Assistant.

### 3.2.6 Editing the disco4iv.xml file (Discoverer Viewer only)

#### 3.2.6.1 What is the disco4iv.xml file?

The disco4iv.xml file on the Master Discoverer Server machine provides Discoverer Viewer with configuration information. Among other things, Discoverer Viewer uses the disco4iv.xml file to identify the Master Discoverer Server machine.

#### 3.2.6.2 Why edit the disco4iv.xml file?

When you install Discoverer Viewer on multiple machines, you need to modify the disco4iv.xml file to identify the Master Discoverer Server.

#### 3.2.6.3 How to edit the disco4iv.xml file and what to change

Before editing the disco4iv.xml file, we strongly recommend that you take a copy of the file for future reference.

1. Open the disco4iv.xml file in the following location on the Master Discoverer Server machine:

   <iSUITES_HOME>/Apache/Apache/htdocs/disco4iv/html

   where <iSUITES_HOME> is the location in which Oracle9i Application Server components are installed.

2. Confirm that the session name entry in the disco4iv.xml file is as follows:

       session name="instance_nameOracleDiscovererSession4"

   where instance_name is the Master Discoverer Server instance name.

3. Confirm that the locator name entry in the disco4iv.xml file is as follows:

       locator name="instance_nameOracleDiscovererLocator4"

   where instance_name is the Master Discoverer Server instance name.

4. Change the path entry in the disco4iv.xml file

   change from: | path="http://%LOCATOR_URL%"
   change to: | path="http://locator_location"
   where: | locator_location is the location of the locator.ior file
   example: | path="http://hostname.domain:PortNo/discwb4/applet/"

5. Remove the following two lines in the disco4iv.xml file:

       <!-- REMOVE THIS COMMENT LINE (A) only if Discoverer 4i Viewer is installed on a different subnet
       than the Discoverer Services, or you are performing a distributed Discoverer Services
       installation

       REMOVE THIS COMMENT LINE (B) only if Discoverer 4i Viewer is installed on a different subnet than
       the Discoverer Services, or you are performing a distributed Discoverer Services installation-->

6. Save the file and exit.

7. Navigate to the <iSUITES_HOME>/Apache/Apache/bin directory and verify the changes you have made by typing the following at the command prompt:

       > apachectl configtest

   If the `Syntax OK' message does not appear, review the changes you have made, correct any mistakes, and run the above command again.

   When the changes you have made are syntactically correct, the message `Syntax OK' appears and you can go on to the next step.

8. Restart the Oracle HTTP Server by typing the following at the command prompt:

       > apachectl restart

   The message `apachectl restart: httpd restarted' confirms that the Oracle HTTP Server has successfully restarted.

   For the changes you have made to the disco4iv.xml file to take effect, you must restart the Discoverer Services components (for more information, refer to Section 2.7 "Restarting Discoverer 4i System").

### 3.2.7 Confirming connection to the Additional Discoverer Server

To confirm that the creation of Additional Discoverer Server machines has been successful, we recommend that you connect to each Additional Discoverer Server machine as follows:

1. Start a Web browser on a client machine.

2. Connect to the Master Discoverer Server machine by typing the following URL:

       http://hostname.domain/discoverer4i/viewer

   where hostname.domain is the fully qualified name of the Master Discoverer Server machine.

   A process starts on the first Additional Discoverer Server machine specified in the pref.txt file and the Oracle Discoverer 4i Viewer login screen appears.

3. To confirm that the installation was successful, type the following at the command prompt on the first Additional Discoverer Server machine to see details of the Discoverer process that has started:

       > ps -A|grep dis4ws

4. Repeat the above steps for each Additional Discoverer Server machine specified in the pref.txt file.

| Copyright © 2000 Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index