BuildForge Help

Configure SSL Support for Tomcat (Quick Report)

The Web browser client and the Tomcat Web server subcomponent of the Management Console communicate over an HTTP connection. Tomcat is required to use the Quick Report reporting feature, a separately licensed option in Build Forge.

This section describes how to configure Tomcat for SSL to secure the HTTP connection. To do this, you must download some additional software, configure Tomcat for SSL, and create self-signed certificates.

These instructions assume that the Tomcat Web server subcomponent is installed on the Management Console host.

Stop the Build Forge Engine

Stop the Build Forge engine if it is running on the Management Console host

Windows
Select Start > Programs > IBM Rational Build Forge Management Console > Stop Engine Service.
UNIX/Linux
Stop the Build Forge engine by using one of the following options:
  • If a Build Forge rc script exists (typically in /etc/rc.d/init.d):
    $ /<rc_path>/buildforge stop
  • If a Build Forge rc script does not exist, determine the process ID and use kill command:
    $ ps aux | grep buildforge
    $ kill ${<PID>}
    

Download and Install Java JDK

Java JDK
When you installed and configured Apache Tomcat for reporting, you installed a version of the IBM or Sun Java JDK that contains the keytool utility.
Verify that $JAVA_HOME points to the Java JDK installation on the Management Console host so that the keytool is available to the OpenSSL application.
Note: Installing and configuring Apache Tomcat for reporting is a prerequisite to configuring SSL support for Tomcat (Quick Report).

Create Certificate Keystore and a Self-Signed Certificate

Execute the Java keytool command to create a keystore and self-signed certificate. (The keytool is included with the Java 1.5 JDK.)

Windows
Run the keytool command from the <JAVA_HOME>\bin directory:
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore <path_to_keystore>
UNIX/Linux
Run the keytool command from the <JAVA_HOME>/bin directory:
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore <path_to_keystore>

After executing the keytool command, you are prompted for a keytool password. You are also prompted for a key password for the certificate. The keytool password and the key password for the certificate must be the same. (You must provide the keytool password later when you configure Tomcat.)

Configure Tomcat for SSL

Configure your secure socket in the $CATALINA_HOME/conf/server.xml file. $CATALINA_HOME is the Tomcat installation directory.

Complete these steps for your Windows or UNIX/Linux installation:

  1. Open the server.xml file in a text editor.
  2. Locate the SSL connector element and uncomment the following lines:
    <!--
    <Connector port="8443" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThread="75"
    enableLookups="false" disableUploadTimeout="true"
    acceptCount="100" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"/>
    </Connector>
    -->
  3. At the end of the SSL connector element, add the following attributes for the keystore and certificate:
    keystoreFile="<path_to_keystore_file>"
    keystorePass="<password>"
    algorithm="IbmX509"
    Note: If you installed the Sun JDK, the default algorithm is SunX509. So, you can delete the line for the algorithm attribute in Step 3.

Test the Tomcat SSL Configuration

Windows
Start the Build Forge engine in the foreground:

In Windows, select Start > Programs > IBM Rational Build Forge Management Console > Start Engine (Foreground).

Look for Tomcat start up errors.

Unix
Start the Build Forge engine in the foreground (using one of the following options) and look for Tomcat startup errors.
  • If there is an rc file (typically in /etc/rc.d/init.d):
    <path_to_rc_file>/buildforge start 
  • If there is no rc file:
    $ /<bf-install>/Platform/buildforge.pl &

Test the Tomcat HTTPS Connection

Use one of the following options to test the Tomcat HTTPS connection to the Web browser.

Web browser test
  1. Open a Web browser.
  2. In the browser address bar, type https://tomcathost:8443.

    The default Tomcat home page should display.

Reporting application test
  1. Log in to the Management Console.
  2. Select the Reporting tab to verify that it works.
  3. For Quick Report, verify that the protocol is https.