B Manually Managed OracleAS Clusters

Clustering components of a system allows the components to be viewed, functionally, as a single entity from the perspective of a client. This appendix describes the procedures you use to create and configure Manually Managed OracleAS Clusters in the Oracle Application Server middle-tier.

This appendix covers the following topics:

Section B.1, "Overview of Manually Managed OracleAS Clusters"
Section B.2, "Configuring Manually Managed OracleAS Clusters"

Note:

This appendix only covers information on Manually Managed Oracle Application Server Clusters. Read this appendix when using a DCM-Managed OracleAS Cluster is either not desirable or not feasible.

B.1 Overview of Manually Managed OracleAS Clusters

Oracle Application Server consists of many components that can be deployed in distributed topologies. Clustering, which unites various Oracle Application Server components to provide scalable and unified functionality with redundancy should any individual components fail, enables high availability for Oracle Application Server.

Review the following terms from Section 1.2.1, "Terminology" before reading this appendix:

Oracle Application Server Instance
Oracle Application Server Farm
Oracle Application Server Cluster
Oracle Application Server Cluster (OC4J)

In addition, we use the following term in this appendix:

Component Instance: Component instances include a single Oracle HTTP Server process or multiple Oracle Application Server Containers for J2EE (OC4J) instances.

B.1.1 Oracle Application Server Manually Managed Clusters

The Oracle Application Server components that constitute an OracleAS Cluster include:

Oracle Process Manager and Notification Server (OPMN) which provides process death detection and process restarting in the event that problems are detected for monitored processes, and channels notifications between the different processes.
Distributed Configuration Management (DCM) distributes the configuration information across the components in the OracleAS Cluster, and also saves the configuration to the repository.
DCM Repository is a vital part of the whole OracleAS Infrastructure that provides the Management Services. The DCM Repository stores the configuration information for the Oracle Application Server Instances, OracleAS Cluster and the whole OracleAS Farm.
mod_oc4j plugs into Oracle HTTP Server, provides configurable and intelligent routing for incoming requests to all OC4J instances using AJP. Requests are routed only to processes and components that mod_oc4J determines to be alive, through communication with OPMN.

B.1.2 What Are Manually Managed OracleAS Clusters?

Manually Managed Oracle Application Server Clusters rely on the administrators to manually configure each instance within the OracleAS Cluster. With a Manually Managed Oracle Application Server Cluster, it is the administrator's job to make a group of application server instances function as an OracleAS Cluster.

Manually Managed OracleAS Clusters provide the following load balancing and high-availability services:

Load-balance requests across all instances of the application server in the Manually Managed OracleAS Cluster.
Replicate session state across all clustered instances in the Manually Managed OracleAS Cluster.
In the event of a node or container failure, transparently fail over requests to a surviving node or container in the Manually Managed OracleAS Cluster.

Using Manually Managed OracleAS Clusters, each Oracle Application Server Instance must be managed independently. The administrator needs to make configuration changes manually to each instance and the changes need to be identical for each instance. Applications deployed to one instance must be individually deployed to all other instances in the Manually Managed OracleAS Cluster.

In essence, a Manually Managed Oracle Application Server Cluster provides scalability and availability, but not manageability. The administrator has the responsibility to synchronize the configuration of the Oracle Application Server Instances across the Manually Managed OracleAS Cluster.

B.1.3 When Do I Need to Use a Manually Managed OracleAS Cluster?

In environments where using a DCM-Managed OracleAS Cluster is either not desirable or not feasible, you have the option to use a Manually Managed OracleAS Cluster.

This section covers the following:

Section B.1.3.1, "No Database Requirement for Manually Managed OracleAS Cluster"
Section B.1.3.2, "Tiered Deployment Requirement for Manually Managed OracleAS Cluster"
Section B.1.3.3, "Tiered Deployment with Security Requirement"

Note:

We recommend using a DCM-Managed OracleAS Cluster wherever possible. A DCM-Managed OracleAS Cluster provides manageability along with scalability and availability and takes care of synchronization of application server instance configuration across the OracleAS Cluster.

B.1.3.1 No Database Requirement for Manually Managed OracleAS Cluster

Starting with Oracle Application Server 10g, you have the option of using an OracleAS File-based Farm, which in many cases enables you to avoid using a Manually Managed OracleAS Cluster. In releases prior to Oracle Application Server 10g, a primary reason why people used a Manually Managed OracleAS Cluster was to avoid using a database for storing the DCM Repository. In Oracle Application Server 10g, using an OracleAS File-based Farm, you can configure a DCM-Managed OracleAS Cluster without storing the DCM Repository in a database. To avoid using a database to store DCM configuration repository information, you should use a DCM-Managed OracleAS Cluster with a OracleAS File-based Farm. In this case, a Manually Managed OracleAS Cluster is not required.

B.1.3.2 Tiered Deployment Requirement for Manually Managed OracleAS Cluster

Using a DCM-Managed OracleAS Cluster you can also deploy components in a tiered deployment, where the OracleAS Web Cache, Oracle HTTP Server, OC4J and database are running on different tiers. In this case, depending on how you configure each tier, it is possible to use a DCM-Managed OracleAS Cluster instead of a Manually Managed OracleAS Cluster. However, in some cases a tiered deployment does require the use of a Manually Managed OracleAS Cluster.While you cannot selectively install the Oracle Application Server components that you want to use on a particular tier, you can either stop or disable non-required components on a particular tier. For example, a J2EE & Web Cache type install installs Oracle HTTP Server and OC4J, but if you do not want to run OC4J on that tier, you can either stop or disable the OC4J component in that Oracle Application Server Instance.

If you decide to stop the non-required components on a tier, as compared to disabling the components, then you can use a DCM-Managed OracleAS Cluster.

Stopping Non-Required Components

If you don't have the requirement to disable the tiered deployment non-required Oracle Application Server components on a particular tier, then you can simply stop them and put all your tiers in one OracleAS Farm. Using this configuration option, for a tiered deployment, you can create a DCM-Managed OracleAS Cluster and avoid using a Manually Managed OracleAS Cluster.
Disabling Non-Required Components

In cases where it is a business requirement to disable the non-required tiered deployment components on a particular tier, you need to use a Manually Managed OracleAS Cluster.

Using a DCM-Managed OracleAS Cluster, you cannot selectively disable components in an Oracle Application Server Instance. In this configuration, disabling a component in one Oracle Application Server Instance would also disabled the component in all the Oracle Application Server Instances in the DCM-Managed OracleAS Cluster. For example, if you disable Oracle HTTP Server in one Oracle Application Server Instance, DCM disables Oracle HTTP Servers in all Oracle Application Server Instances that are in the DCM-Managed OracleAS Cluster.

Thus, if it is required to disable the components in a particular tier, then you cannot use a DCM-Managed OracleAS Cluster.

However, using this type of configuration you can put all of the tiers in an OracleAS Farm, as standalone instances that are not part of a DCM-Managed OracleAS Cluster (this can simplify Manually Managed OracleAS Cluster configuration by eliminating the step of associating application server instances that is required to configure a Manually Managed OracleAS Cluster.)

See Also:
Section B.2.1, "Associating Oracle Application Server Instances Together"

B.1.3.3 Tiered Deployment with Security Requirement

In cases where a tiered deployment includes special security requirements, the configuration could prevent the use of a DCM-Managed OracleAS Cluster. In this case, you may need to configure and use a Manually Managed OracleAS Cluster to support a highly available system.

B.2 Configuring Manually Managed OracleAS Clusters

This section covers the steps you need to follow to configure a Manually Managed OracleAS Cluster.

For this section, we assume the following use case:

A Manually Managed OracleAS Cluster is required for the purpose of a J2EE application, myapp.
The Manually Managed OracleAS Cluster will have two standalone instances, not part of an OracleAS Farm. The instances are named inst1 and inst2.
The two Oracle Application Server Instances (inst1 and inst2) are installed on either two different nodes or on one node but in two separate ORACLE_HOME directories.
J2EE application, myapp is deployed on an OC4J instance named home, that is not used by any of the components internally.

This section covers the following:

Section B.2.1, "Associating Oracle Application Server Instances Together"
Section B.2.2, "Configuring OC4J Instances for State Replication"
Section B.2.3, "Configuring the J2EE Application Properties"
Section B.2.4, "Configuring Oracle HTTP Server for Failover and Load Balancing"

B.2.1 Associating Oracle Application Server Instances Together

For this use case we assume that the Oracle Application Server Instances are standalone instances, meaning they are not associated with an OracleAS Farm. But if in your case the Oracle Application Server Instances are associated with an OracleAS Farm then you can skip this section.

On both inst1 and inst2, run following command, on UNIX systems:
```
$ORACLE_HOME/dcm/bin/dcmctl getOPMNPort
```
On Windows systems:
```
%ORACLE_HOME%\dcm\bin\dcmctl getOPMNPort
```
This returns the hostname and the ONS remote port for the local application server instance (from the local ons.conf file). The output will be of the form:

IPaddress:PortNumber,

For example:
```
127.2.141.148:6200
```
We will refer the output from inst1 as <IP of inst1:Port of inst1> and output from inst2 as <IP of inst2:Port of inst2>.

On inst1, run following command on UNIX systems:

$ORACLE_HOME/dcm/bin/dcmctl addOPMNLink <IP of inst2:Port of inst2>

On Windows systems:

%ORACLE_HOME%\dcm\bin\dcmctl addOPMNLink <IP of inst2:Port of inst2>

On inst2, run following command on UNIX systems:

$ORACLE_HOME/dcm/bin/dcmctl addOPMNLink <IP of inst1:Port of inst1>

On Windows systems:

%ORACLE_HOME%\dcm\bin\dcmctl addOPMNLink <IP of inst1:Port of inst1>

Running these three steps configures the OPMN processes to communicate with each other, allowing OPMN to monitor Oracle Application Server components across the instances.

When you associate Oracle Application Server instances, note the following:

To run addOPMNLink, all instances must be J2EE and Web Cache instances and the instances must not be part of an OracleAS Farm (associated with a repository); otherwise, the command will fail.
If you would like to change the ONS remote port for an instance in a Manually Managed OracleAS Cluster, you must remove the instance from the cluster using removeOPMNLink, change the remote port, and add the instance to the cluster again using addOPMNLink. You must repeat the command in every Oracle home that is part of the Manually Managed OracleAS Cluster.
If you create a cluster and then want to add another instance to the cluster, you must run the command again in all Oracle homes that are part of the Manually Managed Oracle Application Server Cluster.

B.2.2 Configuring OC4J Instances for State Replication

To assure that Oracle Application Server maintains, across the Manually Managed OracleAS Cluster, the state of stateful applications you need to configure state replication for Web and EJB applications. Replication properties are at an OC4J instance level and not at the J2EE application level, meaning that once enabled these are enabled for all the J2EE applications deployed on the OC4J Instance.

Session state for Web applications is replicated in OC4J islands with the same name across application boundaries and across the OracleAS Cluster. To assure high availability with stateful applications, the OC4J island names must be the same in each OC4J instance across the cluster.

Note:

If you do not require session state replication or if your J2EE application is stateless, you can skip this section.

This section covers the following topics:

Section B.2.2.1, "Configuring State Replication for Web Applications"
Section B.2.2.2, "Configuring State Replication for EJB Applications"

B.2.2.1 Configuring State Replication for Web Applications

To configure state replication for stateful Web applications, do the following on both instances inst1 and inst2:

Invoke Application Server Control Console and navigate to the Home Page of the "home" OC4J instance.
Select the Administration link.
Select Replication Properties in the Instance Properties column.
Scroll down to the Web Applications section.
Select the Replicate session state checkbox.

Optionally, you can provide the multicast host IP address and port number. If you do not provide the host and port for the multicast address, it defaults to host IP address 230.0.0.1 and port number 9127. The host IP address must be between 224.0.0.2 through 239.255.255.255. Do not use the same multicast address for both HTTP and EJB multicast addresses.

B.2.2.2 Configuring State Replication for EJB Applications

To configure state replication for EJB applications, do the following on both instances inst1 and inst2:

Invoke Application Server Control Console and navigate to the Home Page of the "home" OC4J instance.
Select the Administration link.
Select Replication Properties in the Instance Properties column.
In the EJB Applications section, select the Replicate State checkbox.

Optionally, you can provide the multicast host IP address and port number. If you do not provide the host and port for the multicast address, it defaults to host IP address 230.0.0.1 and port number 23791. The host IP address must be between 224.0.0.2 through 239.255.255.255. Do not use the same multicast address for both HTTP and EJB multicast addresses.
Provide the username and password, which is used to authenticate itself to other hosts in the cluster. If the username and password are different for other hosts in the cluster, they will fail to communicate. You can have multiple username and password combinations within a multicast address. Those with the same username/password combinations will be considered a unique cluster.
Provide RMI Server Host name; this is usually the name of the machine where the OC4J instance is running.
Click Apply and then OK to confirm.

B.2.3 Configuring the J2EE Application Properties

For J2EE applications to be cluster aware, you need to make the following changes in each of the J2EE applications on instances inst1 and inst2.

Add <distributable/> tag in web.xml.

If the Web application is serializable, you must add this tag to the web.xml file.

The following shows an example of this tag added to web.xml:
```
<web-app>
 <distributable/>
   <servlet>
   ...
   </servlet>
</web-app>
```
Add <cluster-config> Tag in orion-web.xml.

The following shows an example of this tag added to orion-web.xml:
```
<orion-web-app ...>
  ...
   <cluster-config/>
</orion-web-app>
```
Add replication attribute in orion-ejb-jar.xml.

Modify the orion-ejb-jar.xml file to add the state replication configuration for stateful session beans. Since you configure the replication type for the stateful session bean within the bean deployment descriptor, each bean can use a different type of replication (either VMTermination or EndOfCall).

The following shows an example of this attributed added to orion-ejb-jar.xml:
```
<session-deployment ... replication="EndOfCall" />
```

B.2.4 Configuring Oracle HTTP Server for Failover and Load Balancing

The module mod_oc4j in the Oracle HTTP Server identifies the requests it needs to act on, determines which OC4J to route those requests to, and communicates with a particular process. Every J2EE (web) application when deployed needs to be associated with a root context. This root context, that is the URL prefix, acts as the identifier of requests that need to be handled by mod_oc4j. Requests are routed only to OC4J instances and processes that mod_oc4J determines to be alive, through communication with the OPMN.

All mod_oc4j related configuration information is kept in the mod_oc4j.conf file. Oracle HTTP Server uses an Oc4jMount directive to map the root context to the OC4J instance where application was deployed.

Oracle HTTP Server keeps a table of available OC4J instances and load balancing information. To configure a Manually Managed OracleAS Cluster, you need to update the mod_oc4j.conf configuration to make mod_oc4j aware of the other instances so that Oracle HTTP Servers in the Manually Managed OracleAS Cluster can send requests to the OC4J instances in other Oracle Application Server Instances across the Manually Managed OracleAS Cluster (incase the local OC4J instance goes down).

This section covers the following:

Section B.2.4.1, "Understanding mod_oc4j Request Routing"
Section B.2.4.2, "Identifying the Instance Names"
Section B.2.4.3, "Configuring mod_oc4j Request Routing"

B.2.4.1 Understanding mod_oc4j Request Routing

Oracle HTTP Server uses the Oc4jMount directives defined in mod_oc4j.conf file to route requests containing a particular path to a destination. A destination can be a single OC4J process or a set of OC4J instances.

The syntax for the Oc4jMount directive is as follows:

Oc4jMount path [destination]

Where path is the context root, it must be the same as the application context root specified during application deployment and where destination is one of these types:ajp13_dest

cluster_dest

instance_dest

A portion of the Oc4jMount section of a default mod_oc4j.conf file is shown:

Oc4jMount /j2ee/*
Oc4jMount /webapp home
Oc4jMount /webapp/* home

See Also:

Oracle HTTP Server Administrator's Guide

B.2.4.2 Identifying the Instance Names

Identify the fully qualified names of each Oracle Application Server Instances that will be participating in the Manually Managed OracleAS Cluster.

On both inst1 and inst2, run following command, on UNIX systems:

$ORACLE_HOME/dcm/bin/dcmctl whichInstance

On Windows systems:

%ORACLE_HOME%\dcm\bin\dcmctl whichInstance

This command returns the name of the local application server instance that you should use in the following section (the output from inst1 is <inst1_name> and output from inst2 as <inst2_name>).

B.2.4.3 Configuring mod_oc4j Request Routing

The default mount points only indicate the local OC4J instance. For this configuration it is necessary to edit the Oc4jMount directives to point to each Oracle Application Server Instance and OC4J instance in the Manually Managed OracleAS Cluster.

The following edits should be done after an application is deployed, not before, since part of the deployment process an Oc4jMount directive is written to the mod_oc4j.conf file. Do the following on both Oracle Application Server Instances inst1 and inst2 (or do it only on one instance, for example inst1, if you wish to use Oracle HTTP Server of inst1 and would never use Oracle HTTP Server of inst2):

Invoke Application Server Control Console and navigate to the Home Page of the "home" OC4J and navigate to Home Page of "HTTP_Server".
Select the Administration link and then select Advance Server Properties.
Select mod_oc4j.conf in the File Name column.
In the editor, scroll down and find the Oc4jMount directives for the application you deployed and change these as follows:
```
Oc4jMount /myapp instance://<inst1_name>:home, <inst2_name>:home
Oc4jMount /myapp/* instance://<inst1_name>:home, <inst2_name>:home
```
This configuration automatically makes these instances (inst1 and inst2) failover candidates for each other.
Click Apply and then OK to confirm.

This step requires restarting, or stopping and then starting the Oracle HTTP Server component.