Jazz Library TN0032: Configuring proxy server caching with Rational Team Concert
Author name

workflow-management,rational-team-concert

Mon, 10 Aug 2009
5 min read
0

TN0032: Configuring proxy server caching with Rational Team Concert

Last Updated: August 10, 2009
Author:  Anuradha Ramamoorthy, Ken Tessier, Todd Lainhart
Build basis: Rational Team Concert 2.0

For RTC 2.0.0.1, this tech note has been replaced with this article. 

Summary

You can configure the Jazz Team Server with Apache HTTPD to enable caching of artifacts stored in Jazz source control. By caching frequently accessed documents close to the clients that request them, you can reduce network bandwidth and improve retrieval performance over networks with high latency between those clients and the origin servers that they contact.  Consider using this option to improve performance within a secure Wide Area Network (WAN) or if strong security is not a concern.  This feature is available only with Jazz Team Server Standard Edition 1.0.1.

Requirement: Only project areas that are public (rather than private) are candidates for caching.

More Information

The following sections show how to configure Apache HTTPD as a proxy caching server that serves as a Web cache for a Jazz origin server.  Configuration changes to Jazz Team Server are also described.  

Jazz source control supports the caching of artifacts via proxy caching servers that serve as Web caches.  You can increase significantly the speed with which a client retrieves artifacts from an origin server over a network with high latency.  For example, tests have shown that with 150 ms latency over a 1.2M bps bandwidth connection, a 100 to 400 percent improvement in retrieval speed is possible by properly configuring an intermediate proxy caching server and locating it with the requesting client.

The steps described in this document were tested successfully with Apache HTTPD 2.2.9/10 serving as a proxy caching server on Linux serving 250 concurrent clients. When tested on Windows, there were authentication issues between the httpd proxy and a Tomcat origin server, as well as stability issues with httpd when run with more than 100 clients.  Therefore, the steps in this document illustrate running httpd on Linux, and we recommend doing the same.

Security considerations

There are two server configuration restrictions that apply when enabling a proxy caching server between the Rational Team Concert client and the Jazz origin server: the Jazz server must be setup for non-secure HTTP access; any project areas with content that are eligible for caching must be marked as “public”.

You can configure caching only for nonsecure HTTP access to the proxy cache server and the Jazz origin server.  Nonsecure HTTP access means that the client credentials, server requests, and responses are sent over the network as cleartext with no encryption beyond what is offered via form-based authentication. Review your security needs to determine whether this level of access is appropriate.

Note also that only content responses from public Jazz project areas are eligible for caching by the Jazz Team Server.  By default Jazz project areas are created as public, but you’ll want to review both the project area permissions properties as well as your own security needs to determine if this requirement can be fulfilled.

Configuring Apache HTTPD for caching

To configure Apache httpd to enable caching, you must edit the httpd.conf file, which is located in the apache-installation-directory/conf directory.

The following steps require you to specify configuration directives. See the Apache documentation at http://httpd.apache.org/docs for details about all directives.

  1. Build httpd and enable the proxy and caching modules.  The proxy and caching modules contain the directives that you need to set.  Download the httpd source from http://apache.org and unzip the file.  Navigate to the source root directory.  Open the INSTALL file and review the directions near the beginning of the file that describe how to configure, build, and install the source tree.  Use the configure command with the prefix and enable-modules options to set the installation directory of the installed components, and to build and enable the proxy and caching modules.  For example, the following command sets the installation directory to /var/local/apache2.
    2. ./configure --prefix=/var/local/apache2 --enable-modules="cache disk_cache proxy http_proxy"
    Alternatively, you can use the LoadModule directive to configure httpd to load the proxy and caching modules at runtime. Run the make and make install commands to complete the installation.
  2. Set the location of the disk cache. Find a disk that has enough space to store the cached content. Open the httpd.conf file in a text editor.  Use the CacheRoot directive to identify the root storage directory. The effective userid of the running httpd process must be able to write to this directory.  For example: 
    3. CacheRoot /var/cache/JazzTeamServerCache
  3. Enable caching for the Jazz URI. Use the CacheEnable directive to specify the URLs to cache and the cache type to use. The following example specifies caching for all URLs at or below the Jazz context root. The cache type of disk directs Apache to use the disk-based storage manager. 
    4. CacheEnable disk /jazz
  4. Set up the reverse proxy. Use the ProxyPass directive to map requests to the Jazz URI of a remote Jazz Team Server into the local Jazz Team Server. For example:
    5. ProxyPass /jazz http://example.com:9080/jazz
    Use the ProxyPassReverse directive to have Apache use the absolute URI of the proxy server as values for the Location, Content-Location, and URI headers in HTTP responses. For example: 
    ProxyPassReverse /jazz http://example.com:9080/jazz
    Use the ProxyRequests directive to prevent your caching server from being used as a forward proxy. For example: 
    ProxyRequests Off
    Use the <Proxy> directive to enable all clients to access the proxy server. For example: 
    <Proxy *>
    Order Deny,Allow
    Allow from all
    </Proxy>
  5. Identify the caching server host. The caching server host might use one domain name to identify itself while clients of that server use a different domain name when they attempt to access it. This situation can occur if the caching server host has a DNS alias. To avoid any problems related to the name of the caching server host, use the ServerName directive to set the host name and port that the server uses to identify itself. For example:
    6. ServerName example.com:8080
  6. Collect diagnostic information. To verify that items are being added, retrieved, and rejected from the cache as you expect, use the LogLevel directive to enable httpd logging in debug mode. For example:
    7. LogLevel debug
    The debugging information is stored in apache-installation-directory/logs/error.log.

    Note    : Use debug mode logging only when you are testing the setup or diagnosing a problem. When using debug mode, the log file gets large very quickly.  To find information in the log file related to the caching module, search for mod_cache.

Enabling form-based authentication

When you install the Jazz Team Server, form-based authentication is enabled. To use a Jazz Team Server for proxy caching, you must confirm that form-based authentication is still enabled.

If necessary, edit the web.xml file and context.xml file to enable form-based authentication. If you use the WebSphere Application Server and you modify web.xml, be sure to restart the WebSphere Application Server after you deploy the modified web.xml file.  See References for related Tech Tips.

  1. If you use Apache Tomcat, open the web.xml file in an editor. The web.xml file is stored in the Jazz-Team-Server-installation-directory/server/tomcat/webapps/jazz/WEB-INF directory.  If you use WebSphere Application Server, see TN0014: Updating the Deployment Descriptor for a Previously-Deployed Java EE Web Application Archive (WAR).
    • Confirm that the login-config element specifies FORM for its authentication method. In the following example, the BASIC authentication method is commented out, and the FORM authentication method is not commented:
    <!--
     <login-config>
     <auth-method>BASIC</auth-method>
     </login-config>
    -->
     <login-config>
     <auth-method>FORM</auth-method>
     <form-login-config>
     <form-login-page>/auth/authrequired</form-login-page>
     <form-error-page>/auth/authfailed</form-error-page>
     </form-login-config>
     </login-config>
  2. If you use Apache Tomcat, open the context.xml file in an editor. The context.xml file is stored in the Jazz-Team-Server-installation-directory/server/tomcat/conf/Catalina/localhost directory.
    • Confirm that the Valve element specifies FormAuthenticator as its authenticator valve. For example:
    <Context>
     <ResourceLink name="GlobalUserDatabase"
     global="UserDatabase"
     type="org.apache.catalina.UserDatabase" />
     <Valve className="org.apache.catalina.authenticator.FormAuthenticator"
     disableProxyCaching="false" />
    </Context>

Disabling SSL

When you install the Jazz Team Server, Secure Sockets Layer (SSL) communications protocol is enabled. You must disable SSL for the Jazz Team Server that you use for proxy caching.  To disable SSL:

  1. If you use Apache Tomcat, make sure that you have started the Apache Tomcat server at least once.
  2. See TN0014: Updating the Deployment Descriptor for a Previously-Deployed Java EE Web Application Archive (WAR) for details about editing the deployment descriptor.
    • In the web.xml file, change all occurrences of CONFIDENTIAL to NONE.  Save the file.
  3. If you use Apache Tomcat, navigate to the Jazz-Team-Server-installation-directory/server/tomcat/conf directory.
    • Open the server.xml file in an editor.  Remove the redirectPort attribute from the 9080 Connector element.  Save the file. 
    • Restart the Apache Tomcat server.
  4. Verify that you can login via http://localhost:9080/jazz/admin without being redirected to https://localhost:9443/jazz/admin.

Enabling Tomcat diagnostic output

You can enable diagnostic output for request and response headers. Enable diagnostic output only when you are testing the setup or diagnosing a problem. When using debug mode, the log file gets large very quickly.

  1. Open the server.xml file, which is stored in the Jazz-Team-Server-installation-directory/server/tomcat/conf directory.
  2. Uncomment the following directive:
    3. <Valve className="org.apache.catalina.valves.RequestDumperValve"/>

References

The following Tech Tips contain information related to this topic:

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Mon, 10 Aug 2009