9 Deploying in a Clustered JBoss Application Server Configuration

Note:

JBoss Application Server clustered environments are not supported in Oracle Identity Manager release 9.1.0. See "Certified Components" in Oracle Identity Manager Release Notes for information about certified components.

This chapter describes how to deploy Oracle Identity Manager in a clustered JBoss Application Server environment.

This chapter discusses the following topics:

Overview of Installation in a Clustered Installation
Installing Oracle Identity Manager on the First Node
Copying Oracle Identity Manager to Additional JBoss Application Server Nodes
Setting up the Load Balancer for JBoss Application Server
Installing and Configuring a Database for Oracle Identity Manager
Configuring Oracle Identity Manager on the JBoss Application Server Cluster
Configuring the JBoss Application Server Cluster to Use a Common Database
Starting the JBoss Application Server Cluster

Caution:

Deploying an application in a clustered installation is a complex procedure. This document assumes that you have expertise in installing and using applications in a JBoss Application Server cluster. These instructions provide the Oracle Identity Manager-specific details only. They are not complete instructions for setting up a JBoss Application Server cluster. For more information about clustering, see JBoss Application Server documentation.

9.1 Overview of Installation in a Clustered Installation

To install Oracle Identity Manager on a JBoss Application Server cluster, you must complete the following general tasks:

Install Oracle Identity Manager on the first node in your JBoss Application Server cluster.

See "Installing Oracle Identity Manager on the First Node" for more information.
Copy the JBoss Application Server and Oracle Identity Manager installation directories from the first node in your JBoss Application Server cluster to all other nodes. Ensure to maintain the original directory structure throughout this process.

See "Copying Oracle Identity Manager to Additional JBoss Application Server Nodes" for more information.
If you are using Microsoft SQL Server as your database, locate the JDBC driver files (mssqlserver.jar, msbase.jar, and msutil.jar) and copy them to the JBOSS_HOME/server/all/lib directory.

Note:
Microsoft SQL Server is not supported in Oracle Identity Manager release 9.1.0. See "Certified Components" in Oracle Identity Manager Release Notes for information about certified components.

See "Configuring JBoss Application Server for Microsoft SQL Server" for more information.
Set up the load balancer for your JBoss Application Server cluster.

See "Setting up the Load Balancer for JBoss Application Server" for more information.
Perform postinstallation configuration of Oracle Identity Manager on the JBoss Application Server cluster.

See "Configuring Oracle Identity Manager on the JBoss Application Server Cluster" for more information.
Start the cluster.

See "Starting the JBoss Application Server Cluster" for more information.

9.2 Installing Oracle Identity Manager on the First Node

Follow the installation steps for Oracle Identity Manager in "Installing Oracle Identity Manager on Microsoft Windows" or "Installing Oracle Identity Manager on UNIX" to install Oracle Identity Manager on the initial node in your JBoss Application Server cluster.

9.3 Copying Oracle Identity Manager to Additional JBoss Application Server Nodes

Ensure that the name and path of the JAVA_HOME directory used by Oracle Identity Manager is the same across all the nodes of the cluster.

Then, for each additional node in your JBoss Application Server cluster, copy the JBoss and Oracle Identity Manager installation directories from the first node to all other nodes, making sure to maintain the original directory structure and hierarchy throughout this process.

9.4 Setting up the Load Balancer for JBoss Application Server

The procedure for installing a load balancer for your JBoss Application Server cluster varies according to the operating system running on the host computers on which the JBoss Application Server nodes are installed.

9.4.1 Setting Up a Load Balancer for JBoss Application Server on Microsoft Windows

To set up a load balancer on Microsoft Windows:

Download the latest distribution package for the Apache2 Web server from Apache.org, then install the Apache server in a directory that this document henceforth refers to as APACHE_HOME.
Download the latest distribution package mod_jk 1.2.x from the Tomcat connector section page at the following URL: http://tomcat.apache.org/download-connectors.cgi.
Copy the library named mod_jk.so to the APACHE_HOME\modules directory.
Set up Apache to use modjk by adding the following line (and the accompanying comment line) as the last line of the APACHE_HOME\conf\httpd.conf file:

# Include mod_jk configuration file

Include conf/mod_jk.conf

In the directory APACHE_HOME\conf, create a configuration file to forward requests to JBoss Application Server instances.

Name this file as mod_jk.conf and populate with the following lines:

# Load mod_jk module
     # Specify the filename of the mod_jk lib
     LoadModule jk_module modules/mod_jk.so
     # Where to find workers.properties
     JkWorkersFile conf/workers.properties
     # Where to put jk logs
     JkLogFile logs/mod_jk.log
      # Set the jk log level [debug/error/info]
     JkLogLevel info 
     # Select the log format
     JkLogStampFormat  "[%a %b %d %H:%M:%S %Y]"
     # JkOptions indicates to send SSK KEY SIZE
     JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
     # JkRequestLogFormat
     JkRequestLogFormat "%w %V %T"       
     # Mount your applications
     JkMount /application/* loadbalancer
     # You can use external file for mount points.
     # It will be checked for updates each 60 seconds.
     # The format of the file is: /url=worker
     # /examples/*=loadbalancer
     JkMountFile conf/uriworkermap.properties               
     # Add shared memory.
     # This directive is present with 1.2.10 and
     # later versions of mod_jk, and is needed for
     # for load balancing to work properly
     JkShmFile logs/jk.shm             
     # Add jkstatus for managing runtime data
     <Location /jkstatus/>
     JkMount status
     Order deny,allow
     Deny from all
     Allow from all
     </Location>

Review the directive descriptions located at the Apache Tomcat Connector Documentation Index Web site at the following URL:

http://tomcat.apache.org/connectors-doc/

Ensure to follow the guidelines concerning Apache cache size.

In the APACHE_HOME\conf directory, create a file named workers.properties and populate it with the following lines:

# Define list of workers that will be used
     # for mapping requests
       worker.list=loadbalancer,status
     # Define Node1
     # modify the host as your host IP or DNS name.
       worker.node1.port=8009
       worker.node1.host=IP of node1
       worker.node1.type=ajp13
       worker.node1.lbfactor=1
     # worker.node1.local_worker=1 (1)
       worker.node1.cachesize=10
     # Define Node2
     # modify the host as your host IP or DNS name.
       worker.node2.port=8009
       worker.node2.host= IP of node2
       worker.node2.type=ajp13
       worker.node2.lbfactor=1
     # worker.node2.local_worker=1 (1)
       worker.node2.cachesize=10
     # Load-balancing behavior
       worker.loadbalancer.type=lb
       worker.loadbalancer.balance_workers=node1,node2
       worker.loadbalancer.sticky_session=1
     # worker.loadbalancer.local_worker_only=1
     # worker.list=loadbalancer

If your JBoss Application Server cluster contains more than two nodes, then you must add extra lines to the workers.properties file in the APACHE_HOME\conf directory.

For example, if you have three nodes, you must add the following lines.
```
# modify the host as your host IP or DNS name.
       worker.node3.port=8009
       worker.node3.host= IP of node3
       worker.node3.type=ajp13
       worker.node3.lbfactor=1
     # worker.node3.local_worker=1 (1)     
   worker.node3.cachesize=10
```
For each subsequent node, you must add the preceding group of lines again, except that you must change all references to node3, node4, node5, or node 6, and so on as appropriate.

In the APACHE_HOME\conf directory, create the uriworkermap.properties file, which will hold the URL mappings Apache forwards to Tomcat.

This file enables mod_jk to forward to Tomcat requests from /mx-console, /web-console, /xlWebApp, /xlScheduler as well as /Nexaweb. The syntax for each line is /url=worker_name. Paste this example into the file you created:

# Simple worker configuration file
     # Mount the Servlet context to the ajp13 worker
     /jmx-console=loadbalancer
     /jmx-console/*=loadbalancer
     /web-console=loadbalancer
     /web-console/*=loadbalancer
     /xlWebApp=loadbalancer
     /xlWebApp/*=loadbalancer
     /xlScheduler=loadbalancer
     /xlScheduler/*=loadbalancer
     /Nexaweb=loadbalancer
     /Nexaweb/*=loadbalancer

Start Apache by starting Microsoft Windows Explorer, navigating to the directory APACHE_HOME\bin, then double clicking Apache.exe.

9.4.2 Setting Up a Load Balancer for JBoss Application Server on UNIX

To set up the load balancer on UNIX:

Download the binary file for Apache 2.0 for UNIX from the following URL:

http://httpd.apache.org/download.cgi
Run the following commands to install Apache:
1. tar xvfz httpd-2.0.54.tar.gz
2. cd httpd-2.0.54
3. ./configure --prefix=/opt/apache2 --enable-module=so
4. make
5. make install
Download the jakarta-tomcat-connectors-1.2.14-src.tar.gz file from the Apache Software Foundation Web site by searching at the following URL: http://www.apache.org/
Run the following commands to install the connector:
1. tar xzvf jakarta-tomcat-connectors-1.2.14-src.tar.gz
2. cd jakarta-tomcat-connectors-1.2.14-src/jk/native
3. chmod 755 buildconf.sh
4. ./buildconf.sh
5. ./configure --with-apxs=/opt/apache2/bin/apxs
6. make
7. make install
8. cd / jakarta-tomcat-connectors-jk1.2.14-src/jk/native/apache-2.0/
9. cp mod_jk.so /opt/apache2/modules/
Complete steps 4 to 8 in the procedure "Setting Up a Load Balancer for JBoss Application Server on Microsoft Windows" on page 9-3 as they are the same steps for Microsoft Windows and UNIX.
Navigate to the APACHE_HOME/bin/ directory, then run the following command:

./apachectl start

9.5 Installing and Configuring a Database for Oracle Identity Manager

Refer to Chapter 4, "Installing and Configuring a Database For Oracle Identity Manager" for information.

9.6 Configuring Oracle Identity Manager on the JBoss Application Server Cluster

After you install Oracle Identity Manager on your JBoss Application Server cluster, you must perform certain configuration steps on each node in the cluster.

To configure Oracle Identity Manager on your JBoss Application Server cluster:

For each successive node in the cluster, navigate to the directory JBOSS_HOME/server/all/deploy/jbossweb-tomcat55.sar/, open server.xml in a text editor, and perform the following steps:
1. Locate the following string:
  
  <Engine name="jboss.web" defaultHost="localhost" jvmRoute
2. Change the value of jvmRoute to the name of the node associated with the computer on which you are currently working. (The name of the node should be node1, node2, or node3, and so on as listed in the workers.properties file associated with the computer on which you are currently working).
  
  For Example:
  
  <Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">

For each successive node in your cluster, navigate to the directory JBOSS_HOME/ server/all/deploy, and open the following files:

cluster-service.xml

tc5-cluster-service.xml

Comment out the following block in both of the preceding files:

<!--
<Config>
            <UDP mcast_addr="228.1.2.3" mcast_port="45566" ip_ttl="8" ip_mcast="true" mcast_send_buf_size="800000" mcast_recv_buf_size="150000" ucast_send_buf_size="800000" ucast_recv_buf_size="150000" loopback="false"/>
            <PING timeout="2000" num_initial_members="3" up_thread="true" down_thread="true"/>
            <MERGE2 min_interval="10000" max_interval="20000"/>            <FD shun="true" up_thread="true" down_thread="true" timeout="2500" max_tries="5"/>
            <VERIFY_SUSPECT timeout="3000" num_msgs="3" up_thread="true" down_thread="true"/>
            <pbcast.NAKACK gc_lag="50" retransmit_timeout="300,600,1200,2400,4800" max_xmit_size="8192" up_thread="true" down_thread="true"/>
            <UNICAST timeout="300,600,1200,2400,4800"                window_size="100" min_threshold="10" down_thread="true"/>
            <pbcast.STABLE desired_avg_gossip="20000"
               up_thread="true" down_thread="true"/>
            <FRAG frag_size="8192" down_thread="true" up_thread="true"/>            <pbcast.GMS join_timeout="5000" join_retry_timeout="2000"               shun="true" print_local_addr="true"/>            <pbcast.STATE_TRANSFER up_thread="true" down_thread="true"/>
         </Config>
 -->

Uncomment the following block in both files:

<Config>
            <TCP bind_addr="thishost" start_port="7800" loopback="true"/>            <TCPPING initial_hosts="thishost[7800],otherhost[7800]" port_range="3" timeout="3500" num_initial_members="3" up_thread="true"               down_thread="true"/>
            <MERGE2 min_interval="5000" max_interval="10000"/>
            <FD shun="true" timeout="2500" max_tries="5" up_thread="true"              down_thread="true" />
            <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false" />
            <pbcast.NAKACK down_thread="true" up_thread="true"               gc_lag="100" retransmit_timeout="3000"/>
            <pbcast.STABLE desired_avg_gossip="20000" down_thread="false"              up_thread="false" />
            <pbcast.GMS join_timeout="5000" join_retry_timeout="2000"              shun="false"  print_local_addr="true" down_thread="true"              up_thread="true"/>
            <pbcast.STATE_TRANSFER up_thread="true" down_thread="true"/>         </Config>

Within the block listed in Step b, replace thishost with the IP of the computer on which you are currently working.

The entire IP list must be surrounded by double quotes. For example: TCPbind_addr="192.168.161.20".
Within the block listed in Step b, replace otherhost with the IP of the other computer in the cluster, or, if the cluster contains more than two nodes, replace otherhost with a comma-delimited list of all the IPs.

The IP must be surrounded by double quotes.

For each successive node in the cluster, modify the OIM_HOME/xellerate/config/xlconfig.xml file.

Locate the setting for the java.naming.provider.url in the <Discovery> section and insert a comma-delimited list of URLs corresponding to all the nodes in cluster.

For example, you might change a string as shown in the following sample:
```
<java.naming.provider.url>
    jnp://localhost:1100
  </java.naming.provider.url>
to the following string: 
 <java.naming.provider.url>
    jnp://<IP of node1>:1100,<IP of node 2>:1100
  </java.naming.provider.url>
```

9.7 Configuring the JBoss Application Server Cluster to Use a Common Database

Perform the following steps on the second and remaining cluster members to configure the cluster to use a common database:

Open the JBOSS_HOME/server/all/deploy-hasingleton/jms/database_name-jdbc2-service.xml in a text editor.

Note that database_name refers to the common database used by the cluster.
In all the queries and statements in the sqlProperties section of the database_name-jdbc2-service.xml, change the names of the tables represented by JMS_MESSAGES and JMS_TRANSACTIONS to new, unique, and valid values.

Add the following statements to the end of the file:

DELETE_TEMPORARY_MESSAGES = DELETE FROM NEW_JMS_MESSAGES_NAME
    WHERE TXOP='T'
CREATE_IDX_MESSAGE_TXOP_TXID = CREATE INDEX
    NEW_JMS_MESSAGES_NAME_TXOP_TXID ON NEW_JMS_MESSAGES_NAME (TXOP, TXID)
CREATE_IDX_MESSAGE_DESTINATION = CREATE INDEX
    NEW_JMS_MESSAGES_NAME_DESTINATION ON NEW_JMS_MESSAGES_NAME(DESTINATION)

Note:

NEW_JMS_MESSAGES_NAME represents the new name of the JMS_MESSAGES tables you changed in step 2.

Save and close the file.

9.8 Starting the JBoss Application Server Cluster

To start the JBoss Application Server cluster on which you have installed and configured Oracle Identity Manager:

Initially, start only one node in the cluster (commonly referred to as the master node).

Navigate to the directory OIM_HOME/xellerate/bin, then run one of the following commands, as appropriate for the operating system on the computer hosting JBoss Application Server and Oracle Identity Manager:

On Microsoft Windows:

xlStartServer.bat

On UNIX:

xlStartServer.sh
On each remaining computer in the cluster, navigate to the directory OIM_HOME/xellerate/bin. Then run one of the following commands, as appropriate for the operating system on the computer hosting JBoss Application Server and Oracle Identity Manager:

On Microsoft Windows:

xlStartServer.bat

On UNIX:

xlStartServer.sh
Access the Administration console by opening a browser and pointing it to the following URL
```
http://IP_of_computer_in_which_apache_server_is_running/xlWebApp
```