6
Configuring Reports Server clusters

This chapter will show you how to configure the Reports Server in a cluster to improve performance and loading balancing. This becomes important as the need to deliver information to a rapidly growing user base becomes more demanding.

Reports Server clustering addresses this demand by leveraging your organization's existing hardware investment by plugging in additional application servers as they are needed. This enables the processing capabilities of your Reports Servers to grow as your organization grows.

Before you begin to configure your Reports Server for clustering, you should be familiar with the basic Reports Server architecture. See Chapter 2, "Publishing Architecture and Concepts" for more information. You must also have already set up your Reports Server using a basic configuration. See Chapter 3, "Configuring the Reports Server" for more information.

6.1 Clustering overview

Suppose that you have three machines configured as Reports Servers that you want to cluster. These machines are described below:

Table 6-1 Example server machines descriptions

Machine/Server TNS name	Description	Master/Slave
NT-1	4 CPU NT server	Master
NT-2	2 CPU NT server	Slave
SUN-1	2 CPU Sun Solaris workstation	Slave

Note: The decision to make the NT-1 machine the master server was arbitrary. The number of CPUs was not a determining factor.

For step-by-step instructions on configuring the Reports Servers in a cluster as described in this overview, see Section 6.2, "Configuring Reports Servers in a cluster example".

You will designate NT-1 as the master, then set the CLUSTERCONFIG parameter to enable this server to recognize NT-2 and SUN-1 as slaves. To simplify this example, the MAXENGINE and MINENGINE for the master and each slave server are set to the number of CPUs available on each machine.

Once configured, you will send report requests to the master server (i.e., SERVER=NT-1) which redirects the reports to the slaves. When the master server is started, it checks the configuration file. The master contacts each of the slave servers in the order that they are listed in the configuration file and notifies them to start up the defined number of engines (e.g., two engines each). When the slave engines are started, they are under the control of the master, which allocates jobs to them using a round-robin algorithm.

Suppose that the master server (i.e., NT-1) receives seven report requests. The master uses its four engines to run the first four reports. For the fifth and sixth reports, the master redirects the requests to NT-2's two engines to run them. When the master receives the seventh report, it redirects the request to SUN-1's first engine to run it. All output is written to a central cache (i.e., one that is shared by all servers). The master sends the output back to the requestor (e.g., a Web browser).

Note: It is possible for slave servers to remain fully functional Reports Servers in their own right if they can start engines independently of the master server. Suppose that the MAXENGINE and MINENGINE parameters of the NT-2 Reports Server's configuration are set to three. This means that three engines are dedicated to the NT-2 Reports Server and can receive requests without the master's knowledge. When configured as a slave server (i.e., the MAXENGINE and MINENGINE parameters in the master configuration for NT-2 are set to two), the NT-2 Reports Server has a total of five engines started: three engines that are dedicated to the NT-2 server and two engines are dedicated slaves to the master.

6.2 Configuring Reports Servers in a cluster example

This section provides step-by step instructions for configuring Reports Servers clusters. This example describes the following:

• enabling communication between the master and slaves

• configuring the master server

• running report requests to clustered servers

• resubmitting jobs when an engine goes down

• adding a server to an existing configuration

In this example, you will configure the server machines for clustering as described in Table 6-1, "Example server machines descriptions".

The following assumptions have also been made for each machine:

• The Oracle Reports Server component has been installed.

• The Reports Server has been configured using the machine name as the TNS service entry name (e.g., NT-1) in the tnsames.ora file. See Section 3.2, "Configuring the Reports Server: Reports Web CGI example" more information about the Reports Server configuration.

• A central file server is running and set up with two directories: a Source directory (where report definition files are stored) and a Cache directory (where all cached report output is sent).

  All engines must write their output to a central cache and all engines read report definition files from a central source directory. A central source directory guarantees that all engines are running the same reports. This also eliminates copying updated report definition files to various locations. A central cache enables the master server to serve duplicate jobs and jobs run within the specified tolerance without going to each slave server's local disk.

• All engines see the same aliases for printers (unless the output is always being sent to the default printer).

6.2.1 Enabling communication between master and slaves

On the NT-1 machine (master):

1. Open the tnsnames.ora located in the ORACLE_HOME\NET80 directory in a text editor, and add the following:

   nt-2.world=(ADDRESS=(PROTOCOL=tcp)(HOST=nt-2)(PORT=1949))
   sun-1.world=(ADDRESS=(PROTOCOL=tcp)(HOST=sun-1)(PORT=1949))
   
   

   where nt-2.world and sun-1.world are the names of the server instances and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance.

On the NT-2 machine (slave):

1. Open the tnsnames.ora located in the ORACLE_HOME\NET80 directory in a text editor, and add the following:

   nt-1.world=(ADDRESS=(PROTOCOL=tcp)(HOST=nt-1)(PORT=1949))
   
   

   where nt-1.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance.

2. Open the nt-2.ora (the Reports Server configuration file) located in the ORACLE_HOME\REPORT60\SERVER directory, and set the INITEGINE parameter to 0. This ensures that the only engines created at start-up are the ones started by the master.

3. Repeat steps 1 and 2 on the SUN-1 server machine. In step 2, edit the sun-1.ora configuration file.

6.2.2 Configuring the master server

In this section your will configure the master using the following settings:

• Edit the master server configuration file to identify the slave servers to the master and to control the number of engines associated with master server.

• Set the parameters in the master server configuration file that defines the following:
  • The engine settings and identifies the cache and source directories.

  • Since there are four CPUs on this machine, you will use four local engines to start at the same time as the server.

  • These four engines will shut down if they are idle for 60 minutes, and will restart after running 50 jobs.

  • The number of processes that can communicate with the server at one time is set to the maximum number of 4096.

• Set the CLUSTERCONFIG parameter to identify the slave servers to the master. In this example, you will start two engines on each slave server when the master is started.

Note that the ENGLIFE and MAXIDLE parameters for the master server's engines are implied for all slave engines.

On the NT-1 server machine (master):

1. Open nt-1.ora (the Report Server configuration file) located on ORACLE_HOME\REPORT60\SERVER directory.

2. Edit the configuration file according to settings below:

   maxconnect=4096
   sourcedir="X:\Source"
   cachedir="X:\Cache"
   cachesize=50
   minengine=0
   maxengine=4
   initengine=4
   maxidle=60
   englife=50
   

   Note: The NT-1 machine is mapped to the central server on the X: drive.

3. Edit the configuration file according to the settings below:

   clusterconfig="(server=nt-2
   minengine=0
   maxengine=2
   initengine=2
   cachedir="W:\Cache")
   (server=sun-1
   minengine=0
   maxengine=2
   initengine=2
   cachedir="/share/Cache")"
   
   

   where:

   server is the TNS service entry name of the slave server.

   minengine is the minimum number of runtime engines this master server should have available to run reports.

   maxengine is the maximum number of runtime engines this master server has available to run reports.

   initengine is the initial number of runtime engines started by this master server.

   cachedir is the central cache directory for this master server.

   Notes:

   • Each slave definition must be surrounded by paretheses.

   • The cache directory setting for the NT and the Unix machines are different. Not all servers need to see the shared file system by the same definition (i.e., the master is mapped to the X: drive, while the slave is mapped to W: drive).

   • The slave servers must have their REPORTS60_PATH environment variable set to /share/Source (for the SUN-1 server machine) and set to W:\Source (for the NT-2 machine).

4. Shut down and restart the master server so that the master server can recognize the new configuration.

This completes the configuration. Eight engines will start when the master server is started.

6.2.3 Running reports in a clustered configuration

To run report requests to Report Servers that have been configured for clustering, you specify the master server in the SERVER command line argument (i.e., SERVER=NT-1) along with any other relevant arguments for the thin client executable. The master server assigns incoming jobs to the engines on the slave servers.

Tip: If you set the REPORTS60_REPORTS_SERVER environment variable to the master server, you can omit the SERVER command line argument. See Appendix C, "Environment Variables" for more information.

See Chapter 4, "Running Report Requests" for more information on the various report request methods you can use.

See Section 6.2.4, "Resubmitting jobs when an engine goes down" if you have problems submitting report requests to the server cluster.

The master server's jobs can be monitored by using the Queue Viewer in the Queue Manager. Refer to the Queue Manager online help for more information.

6.2.4 Resubmitting jobs when an engine goes down

If an engine goes down while a report is running, the Retry settings defined in the SCHEDULE command line argument dictates whether the job will be re-run or not. If no Retry settings have been specified, then the job is lost. This job failure, however, will be logged against the server log file, and displayed in the list of jobs in the Queue Manager. If the command line includes retry settings, then the master server will re-run the job with the next available engine.

Suppose that you have submitted a job with the Retry option set to 2 in the SCHEDULE command line argument. The master server starts the report request on the second slave engine on the NT-2 server. However, the NT-2 server runs out of temporary space and the job terminates. The master server will resubmit the job. Assuming that no other jobs have been submitted, this job is assigned to the first engine on the SUN-1 server.

The retry option is useful for giving you fail-over support, but should be used with caution. For example, setting the retry to a large number may not solve the problem. The resubmitted job may always fail if the underlying problem is with the report itself, not the engine.

6.2.5 Adding another slave server to the master

You want to add another slave server to the existing cluster configuration as defined in the following table:

Table 6-2 Additional server machine description

Machine/Server TNS name	Description	Master/Slave
SUN-2	4 CPU Sun Solaris server	Slave

Note: This exercise assumes that this machine has already been configured as a Reports Server. The TNS service entry name for the Reports Server is the machine name.

On the SUN-2 server machine (slave):

1. Open the sun-2.ora (the Reports Server configuration file) located in the ORACLE_HOME\REPORT60\SERVER directory and add the following:

   nt-1.world=(ADDRESS=(PROTOCOL=tcp)(HOST=nt-1)(PORT=1949))
   
   

   where nt-1.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance.

On the NT-1 server machine (master):

1. Open the tnsnames.ora file located in the ORACLE_HOME\NET80\ADMIN directory and add the following entry:

   sun-2.world=(ADDRESS=(PROTOCOL=tcp)(HOST=sun-1)(PORT=1949))
   
   

   where sun-2.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance.

2. Open the nt-1.ora (Reports Server configuration file) and add the following bolded text to the already existing CLUSTERCONFIG parameter:

   clusterconfig="(server=nt-2
   minengine=0
   maxengine=2
   initengine=2
   cachedir="W:\Cache")
   (server=sun-1
   minengine=0
   maxengine=2
   initengine=2
   cachedir="/share/Cache")
   (server=sun-2
   minengine=0
   maxengine=4
   initengine=4
   cachedir="/share/Cache")"
   
   

3. Shut down and restart the master server so that the master server can recognize the newly configured slave server.

Suppose that while you were configuring the SUN-2 machine as a slave server, another administrator took down the NT-2 machine (e.g., to perform a backup). While the NT-2 machine is still down, you restarted the Reports Server on the NT-1 machine. The NT-1 machine was able to start the slave engines on the two Sun machines, but could not start the slave engines on the NT-2 machine since it was down.

Since the NT-1 server is polling all the slave servers, once the NT-2 machine is brought back up and the Reports Server started, it will be detected automatically by the NT-1 server. When the four slave engines start, they are available to receive jobs from the master.