This section includes all of the procedures needed to install and configure Tomcat Application Clusters. These procedures assume an Administrator has full administrative rights as either administrator or root.
Before Installing a Cluster
The server must be configured to support clustering prior to installing a Tomcat Cluster node.
Clustering is disabled by default and must be enabled. Installing a cluster requires that the application instance be shutdown and restarted.
Configuring in Windows:
1. Go to the Blackboard Learn home, <blackboard_install_directory>\config 2. Open the bb-config.properties file.
3. Search for the bbconfig.tomcat.cluster.enable variable, and modify the default value from 'FALSE' to 'TRUE'.
4. Open the context.xml file and uncomment the option to disable session persistence across Tomcat restarts.
5. Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for each node.
6. Go to <blackboard_install_directory>\tools\admin
7. Launch the Push Config Updates script by running the PushConfigUpdates.bat file.
8. Create a new ServerGroup in Blackboard Learn
a. Navigate to <blackboard_install_directory>\tools\admin b. Create a ServerGroup with a specified port number by running:
ServerGroupManager.bat -c -n <new_group_name> -p
<new_port_number>
Configuring in UNIX:
1. Go to the Blackboard Learn home, <blackboard_install_directory>/config 2. Open the bb-config.properties file.
3. Search for the bbconfig.tomcat.cluster.enable variable, and modify the default value from 'FALSE' to 'TRUE'.
4. Open the context.xml file and uncomment the option to disable session persistence across Tomcat restarts.
5. Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for each node.
6. Go to <blackboard_install_directory>/tools/admin
7. Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh 8. Create a new ServerGroup in Blackboard Learn
a. Navigate to <blackboard_install_directory>/tools/admin b. Create a ServerGroup with a specified port number by issuing:
./ServerGroupManager.sh -c -n <new_group_name> -p
<new_port_number>
Note In a Windows or UNIX load-balanced environment, the PushConfigUpdates script must be run on each load-balanced server. Each Node must have its own ServerGroup.
How to Install
These procedures assume an Administrator has full administrative rights as either administrator or root. Upon creating an individual cluster node, the Blackboard services will need to be shutdown and restarted in order to reset the configuration with the new clustered node.
P r o p e r t y D e s c r i p t i o n
Cluster ID Must be a unique name with no spaces between any of the letters. Best practice is to identify one naming convention for all nodes and increment numerically to differentiate servers and nodes. Example: Blackboard1 or Blackboard2.
Server
Shutdown Port
Must be a unique port in order to connect to the JVM for the clustered node and shut it down. By default the primary application server installed with Blackboard runs on port 8005, therefore a new value must be supplied to avoid port socket contention. Best practice is to increment the current server shutdown port by 1000.
JK Connector Port
Must be a unique port in order for the web server to communicate to each clustered node. The default port is 8009. Best practice is to increment the current jk connector port by 1000.
Cluster Listener Port
Must be a unique port for the cluster to replicate session information across the wire. The default port is 4000. Best practice is to increment the current listen port by 1000.
Installing in Windows:
1. Launch the Install Cluster script by running the InstallCluster.batfile. After running the file, you will be prompted for the following information. Configure the settings
according to the previous table.
a. Cluster ID.
b. Server shutdown port.
c. JK Connector port.
d. Cluster Listener port.
2. The cluster is now created.
3. Stop your server by running ServiceController.bat services.stop 4. Start your server by running ServiceController.bat services.start
Installing in UNIX:
1. Launch the Install Cluster script by issuing ./InstallCluster.sh After running the command, you will be prompted for the following information. Configure the settings according to the previous table.
a. Cluster ID.
b. Server shutdown port.
c. JK Connector port.
d. Cluster Listener port.
2. The cluster is now created.
3. Stop your server by issuing ./ServiceController.sh services.stop 4. Start your server by issuing ./ServiceController.sh services.start 5. Run the jps command from your JAVA_HOME to see the bootstrap processes. You
should see one Tomcat Process, and the number of Cluster Process IDs.
Tip UNIX customers should increase the Apache MaxClients value as they add nodes.
Blackboard recommends multiplying the initial value by the number of total JVMs. For example, if MaxClients is 500 for a non-clustered configuration, when 2 JVMs are added, this setting should increase to a minimum of 1500.
Files that are Affected
After a cluster is installed, there are a number of files and directories that are produced. The following table highlights some of these files and directories.
D i r e c t o r y o r F i l e D e s c r i p t i o n
<blackboard_install_di rectory>/apps/tomcat/
cluster/
A new directory that is created when the first node (other than root) is installed.
<blackboard_install_di rectory>/apps/tomcat/c luster/
<node_id>
A new directory that is created for every node added.
Each directory contains files affecting that node:
…/conf/server.xml and log files.
<blackboard_install_di rectory>/apps/tomcat/
conf/jk/workers.proper ties
This file exists before adding a node but changes whenever a node is added to include load-balancing information for that node.
For more information about the workers.properties file, see http://tomcat.apache.org.
server.xml A file that allows you to configure Tomcat nodes through the use of XML descriptors.