Skip to main content
Blackboard Help

Load Balancer Guidelines

Blackboard supports load balancing across application servers but does not support any specific hardware load balancer. These general recommendations can be used to configure your load balancer of choice to work best in your particular environment.

SSL off-loading is supported by Blackboard as of Blackboard Learn 9.1 SP 8. To learn more, see  About SSL.

For setup instructions, see Set Up the Hardware Load Balance.

Port Requirements

Use the following ports when configuring your system:

  • HTTP: 80
  • HTTPS: 443
  • Collaboration Server: 8010 and 8011 (Optional: 8443 if the Collaboration Server is using SSL)

Intra-server communication between Learn servers behind the load balancer is essential for proper operation of the learn environment.  The port range 1025 - 65536 is required for communication between app servers.

Identifying the Server for Troubleshooting Purposes

For each server, create a static server.html page that displays its identifying information. Place all of the pages in the /blackboard/docs directory. To view the server.html page for the current server, go to the following URL:

Persistence Requirements

Blackboard recommends configuring the load balancer for cookie-insert-based session affinity. The Blackboard session cookie should be used only as an alternative to the cookie-insert method.

Configure Client IP Address Forwarding

The Client IP Address must be forwarded to ensure logs reflect the client IP Address rather than the load balancer IP Address. Otherwise, log monitoring and forensic capabilities will be limited. Implement this configuration on the load balancer. The load balancer will insert the original client IP Address in an X-Forwarded-For HTTP header.

Update web server logs to extract the X-Forwarded-For HTTP header, and then run PushConfigUpdates. To learn more, see PushConfigUpdates.

Health Check

Blackboard recommends monitoring Tomcat, Apache (Linux), and IIS (Windows) for liveliness to ensure that the load balancer is sending traffic to application servers that are able to handle the traffic.

Health Check Interval

When performing a health check, it is important to set a health check interval that is frequent enough to maintain the health of the application, but not so frequent that it affects performance. When a health check fails for a specific application server, the load balancer redistributes the traffic that was bound for that server to the remaining available servers. This interval should be optimized to ensure that healthy nodes do not inadvertently fail the health check during a full garbage collection by the JVM. Blackboard considers intervals such as one minute or .1 seconds as extreme values and recommends that they be avoided. Blackboard recommends starting with a health check interval of 20 seconds and blocking traffic to a node after three failures (60 seconds).

Idle Timeout

Blackboard recommends that a browser session cookie be inserted at the load balancer so that the session cookie does not time out until the user closes their browser. The idle timeout of the persistence cookie inserted at the load balancer should be set to greater than the Blackboard session timeout.

Distribution Methods

Different algorithms can be used to determine distribution methods. “Round robin” and “least connections” are the two most common load balancing methods used. To avoid overloading any single server in the cluster, select the method that will ensure that each application server receives approximately the same amount of traffic.

Collaboration Server

The Collaboration Server is a standalone service that provides chat and virtual classroom services. Only one Collaboration Server can be active in a load-balanced environment. Attempting to load balance multiple Collaboration Servers will result in users being isolated from each other on different servers. When configuring your load balanced environment, choose one Blackboard application server to run the Collaboration Services. This can be a dedicated Collaboration Server or one of the application servers.

In the standard configuration, the Collaboration Server can be connected to directly through an external hostname. In this configuration end users must have access directly to the Collaboration Server hostname on ports 8010, 8011, and 8443.

Alternatively, the Collaboration Server can be configured to be available through the load balancer. This can mitigate the Collaboration Server as a single point of failure. This can be useful because the standard configuration might make it necessary to change IP configurations or wait for DNS updates in the event of a host failure.

In the event of a Collaboration Server or host failure, you can restore the Collaboration Service by setting to true in the file of one of the other application servers and running PushConfigUpdates. To learn more, see PushConfigUpdates.

In the event of a Collaboration Service failover to another host, all existing sessions will be lost. You must update the parameter in the file of the failover server.

How to Use the Standard Configuration

  1. On each Blackboard Learn application server, set the following parameters in the file:
    1. >Set bbconfig.config.collabserver.fullhostname.default to the fully qualified hostname of the Collaboration Server.
    2. Set to false.

    To learn more, see File.

  2. On the Collaboration Server, in the file, set to true.
  3. Run PushConfigUpdates. To learn more, see PushConfigUpdates.

How to Use the Alternate Configuration

  1. On the load balancer, configure the Collaboration Server to be available on ports 8010, 8011, and 8443 as IP layer 4 services.
  2. On each Blackboard Learn application server, set the following parameters in the file:
    1. Set bbconfig.config.collabserver.fullhostname.default to the fully qualified hostname of the Blackboard load balanced address.
    2. Set to false.

    To learn more, see File.

  3. On the Collaboration Server, in the file, set to true.
  4. Run PushConfigUpdates. To learn more, see PushConfigUpdates.

How to Designate Any Application Server as the Collaboration Server

  1. On any application server, in the file, set to true.
  2. Run ServiceController.bat|sh services.collabserver.start. to learn more, see ServiceController.

Blackboard System Tasks

Certain Blackboard system tasks need to be executed on only one server, while other tasks need to be executed on all servers. These tasks are outlined and configured in the blackboard/config/bb-tasks.xml file.

On All Application Servers

The following tasks must be run on each application server:

  • bb.db.cache
  • bb.log.rotation
  • bb.systeminfo.reporting
  • bb.task.queue
  • bb.monitor.cache
  • bb.monitor.memory
  • bb.monitor.thread

On One Application Server

The following system tasks need to be run on one application server to optimize performance:

  • bb.connect.usersync
  • bb.deployment.reminders
  • bb.deployment.scheduling
  • bb.disk_usage
  • bb.distribution.sendnotification
  • bb.domain.calculation
  • bb.fulltextsearch.indexprocessor
  • bb.portal.emailnotification
  • bb.portal.includeUrl.update
  • bb.recylcebin.cleanup
  • bb.scheduled.workflow.queuer
  • bb.session.invalidation
  • bb.snapshot.session.invalidation
  • bb.stats.purging
  • bb.tracking.reporting
  • bb.userlifecycleevent.dispatcher

The bb-task.xml file will be reset to its default settings when you install any Blackboard Learn software patch or upgrade. You must make the desired changes to this file after every software patch or upgrade.