Troubleshooting an Unresponsive Blackboard Application
January 12, 2011 2 Comments
When troubleshooting any problem in Blackboard it is advisable to first check the system logs, especially if the problem is not forthcoming. This can help indicate the source of the problem or at least provide a starting point. The bb-services log is the primary Blackboard application log and is often the best place to start for any troubleshooting. In the case of an unresponsive application the stdout-stderr log is particularly valuable in determining if the application server’s JVM failed to start or crashed and perhaps an indication why.
Although it would be difficult to exhaustively list every possible cause of an unresponsive application, the following is a list of the more common causes that Blackboard may be unresponsive (i.e. “Service Unavailable”, “Page cannot be displayed”, etc):
The Blackboard application will be unresponsive if its services are not running. Check whether the Blackboard services are running by navigating to Administrative Tools > Services. The following services should be running and set to automatic startup:
3. IIS Admin Service
4. World Wide Web Publishing
If any of these services are not running, open a command prompt and navigate to X:\blackboard\tools\admin and run the following: “ServiceController.bat services.start”
If the services start check the website again (it may take a few minutes for the tomcat to begin serving the Blackboard application.) If the services fail to start check the bb-services-log and stdout-stderr-logs located under X:\blackboard\logs, and X:\blackboard\logs\tomcat respectively for details.
*On collaboration server only.
The blackboard application may be non-responsive or buggy if its services, application pool, and website are not owned by a domain account (this should be a domain account dedicated to Blackboard.) Make sure that the Blackboard services are owned by the by the Blackboard service account and not a local account by navigating to Administrative Tools > Services and check the “Log On As” field of the Bb-Tomcat and Bb-Collab services. If this set to “Local System” then Right Click > Properties > Log On and enter the credentials of the Blackboard service account. After setting the ownership restart both services.
Ensure that the Default Application Pool is owned by the Blackboard service account by Right Click > Properties > Identity within IIS Manager.
Ensure that anonymous access is enabled with the Blackboard service account for the Blackboard website by Right Click > Directory Security > Authentication and access control > Edit within IIS Manager.
Incorrectly specifying the application server, database server, or content share location in bb-config.properties will result in a non-responsive or malfunctioning application.
The Blackboard application \ webserver should be configured with the following syntax:
The database server should be configured with the following syntax:
NOTE: If using the default instance, then “instancename” should be left blank.
The content share should be configured to point at the shared content folder (UNC path if content share is on a different server.) For example:
Although not critical to the function of Blackboard, collaboration and mail must be configured properly within bb-config.properties for these functions to work.
Collaboration should be configured with the following syntax:
NOTE: In a loadbalanced environment run.on.localhost should only be ‘true’ on the dedicated collaboration server. In a single-server environment run.on.localhost should be ‘true’ on the appserver and the collab hostname should be the FQDN of the localhost.
Mail should be configured with the following syntax:
Mismatched passwords between a Blackboard application and Blackboard databases may prevent the application from communicating with its databases. Ensure that the passwords match within bb-config.properties and the databases. The following entries in bb-config.properties should match the passwords of the Blackboard databases’ security logins (bb_bb60, bb_bb60_report, bb_bb60_stats, bbadmin) and the passwords listed in the instance table of the bbadmin database:
The following parameter in bb-config.properties should match the sa password of the database instance where the Blackboard databases reside:
If the Blackboard services are running make sure that the blackboard website is running and that any other site bound to port 80 (i.e. the default website) is stopped or removed from the IIS Manager.
Check whether the Blackboard website is available internally. This can be accomplished by navigating to ‘localhost’ from a browser, or browsing the Blackboard website from IIS. If the Blackboard site can be viewed on the server but not via the internet then a firewall is blocking communication over port 80.
If Java is incorrectly configured the Blackboard application will be unresponsive. Ensure that the JAVA_HOME variable is pointing to the Java JDK folder and the slashes are correct in the bb-config.properties file. Also check that a JAVA_HOME environment variable exists and points to the same folder location. An environment variable can be added by Right-Click My Computer > Properties > Advanced > Environment Variables. The correct syntax in bb-config is as follows:
If Blackboard’s SSL option is enabled and an SSL certificate is not associated with each application server then the Blackboard application will be unresponsive. The SSL certificate may need to be applied after reboots. If the Blackboard installation uses SSL and SSL is associated with each application server (not externally i.e. load balancer), make sure that the SSL certificate is associated with the site:
1. Right-Click the Blackboard website from IIS Manager.
2. Select ‘Properties’.
3. Click the ‘Directory Security’ tab.
4. Under ‘Secure Communication’ check whether the SSL certificate is applied. If not, click on ‘Server Certificate…’ and select the certificate.