Configuring Apache Tomcat

In this section:

This section explains how to manually configure Apache Tomcat for use with WebFOCUS and ReportCaster. The WebFOCUS installation provided the option to install and configure Apache Tomcat for you. If you chose this option and the verification tool ran successfully, you do not need to manually configure Tomcat. However, if you are new to Tomcat or receive errors, you should review this section to understand the configuration process.

There are two configurations available when using Apache Tomcat:

Top of page

Java Memory Requirement

You may need to adjust the Java VM memory options if you run into performance issues.

Open the Tomcat Configuration Utility and select the Java tab, as shown in the following image.

For Java 6 and 7, in the Java Options section, ensure that the following line is added:


Note: This is not needed for Java 8.

Ensure that the Initial memory pool size is at least 256MB and that the Maximum memory pool size is at least 512MB.

Top of page

Preparing Tomcat for WebFOCUS

How to:


It is assumed that Tomcat is installed at this time. If Tomcat is not installed, you can install it from the WebFOCUS Client installation CD or by downloading the installation utility from:

If you chose to have WebFOCUS configure Tomcat for you, the following steps were performed:

The following steps can be performed to further configure Tomcat:

Procedure: How to Set CLASSPATH for the Repository Tables

The JDBC driver location must be in the Tomcat CLASSPATH. Tomcat runs as a Windows service, so CLASSPATH is set in the registry. If you chose to configure Tomcat when you installed WebFOCUS, the install should have set this for you.

To manually set Java Classpath or troubleshoot, check your CLASSPATH field and be sure to include the JDBC driver.

Note: If the driver does not appear, add a semicolon to the end of the Java Classpath field. Then add the absolute path to the JDBC driver for your repository. If more than one file is needed, separate each path with a semicolon. Spaces can occur in directory names, but not between the paths and the semicolons. Be sure to include the file name and not just the directory containing the file. For example:


For information on JDBC drivers, see Additional WebFOCUS Repository Topics and Tasks.

Reference: Tomcat Ports

By default, Tomcat uses the three TCP ports listed below.

Default Port




HTTP Listener Port

You access Tomcat in a web browser using this port. For example:



Connector Port

Web servers route requests to Tomcat on this port. The Tomcat connector (plug-in) for IIS uses this port. If you change this port and use the connector, change the port in the file of the connector.


Shutdown Port

Tomcat uses this port for internal operations and for stopping.

You normally do not need to change these ports. However, if these ports are not available or you want to change them, do the following:

  1. Open the following file in a text editor:
  2. Search for the port numbers you want to replace (8080, 8009, 8005) and replace them with the ports you want to use.
  3. Save and exit the file.

If you change defaults, substitute accordingly in procedures and examples.

Top of page

Creating WebFOCUS Contexts for Tomcat

In this section:

How to:


Configuring Tomcat mainly requires telling Tomcat where WebFOCUS files are located and the context roots in which to use them. For example, you must tell Tomcat to serve files from the WebFOCUS web application:


when it receives a request for the WebFOCUS context root:


By creating this context, you deploy the WebFOCUS web application.

Tomcat can also serve files outside of a web application after it knows their location and context. Therefore, Tomcat can be used as both a web server and application server. On a traditional web server, you create aliases. With Tomcat, an alias is treated like a context root, even when serving files outside of a web application.

Procedure: How to Configure Apache Tomcat
  1. Stop Tomcat from the Windows Services window by right-clicking Apache Tomcat and choosing Stop.
  2. Navigate to the following directory in Windows Explorer or My Computer:

    Note: If you have an existing version of Tomcat, not installed by a 8.x version of WebFOCUS, the directory will be under:


    This directory can contain XML files that define contexts. If the WebFOCUS installation installed and configured Tomcat for you, the following file should appear to define the ibi_apps context that deploys the WebFOCUS directory:


    If you are using Tomcat stand-alone, the following should appear as well:


    The XML files are named for the context root you would use to access the web application and should have the following syntax:

    <?xml version='1.0' encoding='utf-8'?>
    <Context docBase="path_To_WebApplication" path="/contextRoot">



    Is the absolute path to the WAR file or directory you are deploying.


    Is the context root.

    Note: They can optionally contain additional information, as explained in the Tomcat documentation.

    You can create or edit the files in a text editor, such as Notepad.

  3. If the ibi_apps.xml file does not exist, create it. For example:
    <?xml version='1.0' encoding='utf-8'?>
    <Context docBase="C:\ibi\WebFOCUS81\webapps\webfocus" path="/ibi_apps" useHttpOnly="true">

    Be sure to specify the correct directory on your machine and change the context root if you are not using the default (ibi_apps).

  4. If you are using Tomcat stand-alone, create an approot.xml file if it does not exist. For example:
    <?xml version='1.0' encoding='utf-8'?>
    <Context docBase="C:\ibi\apps" path="/approot">

    Be sure to specify the correct directory on your machine.

  5. Restart Tomcat from the Services window.

Reference: Reloading Web Applications

This is not a consideration if you just installed WebFOCUS for the first time, but you should be aware of it for when you install a service pack or new release. When you upgrade WebFOCUS or install a service pack, Tomcat must use the new web applications, rather than cached copies of the old version.

Accessing the Shortcut to the Apache Tomcat Properties Window

You can access the Apache Tomcat Properties window by selecting Programs, Information Builders, Tomcat, and then Tomcat Configuration Utility. The following image shows the Apache Tomcat 8.0.21 for WebFOCUS Properties window.

To change Java memory settings, click the Java tab, as shown in the following image.

If required, you can use this tab to modify the Java memory settings after installation.

Accessing the Tomcat Manager Application

The Tomcat Manager application is packaged with Apache Tomcat. It provides basic functionality to manage web applications that are deployed to Apache Tomcat. It can be used to troubleshoot issues with the deployment or to manually deploy .war files if required. As of WebFOCUS 8, the Tomcat Manager application is not deployed automatically.

Top of page

Verifying the WebFOCUS Configuration With Apache Tomcat

How to:

After finishing the configuration, run test calls to verify operability.

Procedure: How to Verify the WebFOCUS Configuration
  1. If they are not started, start the following:
    • Apache Tomcat
    • WebFOCUS Reporting Server
  2. Enter the following URL in your browser:



    Are the host name and port of the web server. However, if you use an application server only configuration, then these are the host name and HTTP port of the application server. For Tomcat stand-alone configurations, the default port is 8080. If you require SSL, use https instead of http.

    The WebFOCUS Sign In page opens, as shown in the following image.

  3. Sign in as an administrator. The default user name and password is admin and admin.

    The WebFOCUS Business Intelligence Portal Welcome page opens in your web browser.

  4. Click Administration in the top pane, and then select Administration Console, as shown in the following image.

    The WebFOCUS Administration Console opens.

  5. Expand Diagnostics, Verification, and then WebFOCUS Reporting Server, as shown in the following image.

    The following page opens, which lists your WebFOCUS Reporting Server instance if it is available.

  6. Click Test Existing Procedure.

    When Test Existing Procedure is selected and the WebFOCUS Reporting Server is not running or is running with Security enabled (ON), you are prompted for WebFOCUS Reporting Server credentials.

    When credentials are entered and the WebFOCUS Reporting Server is not running, an error message is displayed.

    If the WebFOCUS Reporting Server is running with Security disabled (OFF), then the Run a Stored Procedure page opens, as shown in the following image.

  7. Click Run to run the test procedure.

    A procedure is normally launched using the WebFOCUS Servlet and a sample report should display. You can manually use a servlet to run a procedure, such as carinst.fex, using:

  8. If you are using Tomcat stand-alone, proceed to WebFOCUS Client Post-Installation Tasks.