Running multiple Tomcat versions on the same host

Running multiple Tomcat versions on the same host Installation guide StreamServe 4.x Rev A

Running multiple Tomcat versions on the same host Installation guide StreamServe 4.x Rev A 2005 StreamServe, Inc. StreamServe is a trademark of StreamServe, Inc. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of StreamServe, Inc. Information in this document is subject to change without notice. StreamServe Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in this book. All registered names, product names and trademarks of other companies mentioned in this documentation are used for identification purposes only and are acknowledged as property of the respective company. Companies, names and data used in examples in this document are fictitious unless otherwise noted. StreamServe, Inc. offers no guarantees and assumes no responsibility or liability of any type with respect to third party products and services, including any liability resulting from incompatibility between the third party products and services and the products and services offered by StreamServe, Inc. By using StreamServe and the third party products mentioned in this document, you agree that you will not hold StreamServe, Inc. responsible or liable with respect to the third party products and services or seek to do so. The trademarks, logos, and service marks in this document are the property of StreamServe, Inc. or other third parties. You are not permitted to use the marks without the prior written consent of StreamServe, Inc. or the third party that owns the marks. Use of the StreamServe product with third party products not mentioned in this document is entirely at your own risk, also as regards the StreamServe products. StreamServe Web Site http://www.streamserve.com

3 Contents...5 Issues...5 File directories... 5 TCP ports... 6 Java Virtual Machines... 6 Apache HTTP Server and JK Connectors... 6 Installing two Tomcat instances on the same host...7 Identifying conflicting resources... 7 Reconfiguring Tomcat 3.x with a hard-coded JVM... 8 Reconfiguring Tomcat 4.x with a hard-coded JVM... 9 Reconfiguring Tomcat 4.x with alternate TCP ports... 10 Reconfiguring a frontend Apache HTTP server... 10 Configuring Tomcat 4.x with JK (mod_jk) 1.2x for Apache HTTP 1.3.x... 11 Configuring JK Connector workers... 11 Configuring Apache HTTP Server for JK (mod_jk) 1.2x Connector... 12

4

5 Running multiple Tomcat instances on a single host Sometimes, it is desirable to run multiple instances of the Apache Tomcat server on a single host machine. In the case of StreamServe Interactive Forms and Profile Manager (as of release 4.0), this scenario is sometimes necessary. Interactive Forms was written to use Java Servlet Pages running on Tomcat 4.x, with JDK 1.4.x. Profile Manager, Job Gateway and Web Center were written to use Java Servlets running on Tomcat 3.x, with JRE 1.3.x. Tomcat 4.x should be backwards-compatible with Tomcat 3.x. Servlet Specification 2.3 is backwards-compatible with 2.2, and JSP Specification 1.2 is backwards-compatible with 1.1. However, the different versions of Tomcat use different XML parsers, which are not interchangeable (Crimson vs. Xalan). Going forward, new StreamServe Java servlets and JSPs will use the newer version of Tomcat with its newer XML parsers. This document outlines the major configuration changes required to run two separate Tomcat instances on a single system. It cannot address every potential configuration scenario, nor are the proposed mechanisms the only workable solutions. Issues Running Tomcat 4.x and Tomcat 3.x together on a single system, using all default configuration options, leads to resource contention that prevents them from working properly. To successfully run the two servers together, it is necessary to identify overlapping resources, and reconfigure one server to use alternate resources. File directories Using default settings, directory structure and file location should not be problematic. On most Windows systems, StreamServe Web Center installs Tomcat 3.3a to C:\StreamServeWebInterface\jakarta-tomcat-3.3a and Tomcat 4.1.29 is installed to C:\Program Files\Apache Group\Tomcat 4.1. If the Tomcat servers are not installed to these default locations, or other installation mechanisms are used, manually verify that the paths are not the same to avoid that the programs overwrite each other's files.

6 Issues TCP ports Using default TCP ports will cause conflicts between different Tomcat versions: Tomcat 3.3a usually listens on TCP ports 8007, 8009 and 8080 for AJP12, AJP13, and HTTP, respectively. Tomcat 4.1.29 usually listens on TCP ports 8005, 8009 and 8080 for shutdown/administration, AJP13, and HTTP, respectively. Only one service can listen on any given TCP port, meaning that one of the instances has to be reconfigured. Reconfiguration can either involve changing the TCP listener port, or disabling listeners. Java Virtual Machines Java Developer Kits (JDKs or J2SDKs) are supersets of Java Runtime Environments (JREs or J2REs), and are necessary for compiling and debugging Java code. JDKs are necessary for running Java Server Pages (JSPs), which are uncompiled Java code, while JREs are adequate for running Java Servlets. While JREs and JDKs are licensed free of charge by JVM vendors, such as Sun, IBM and HP, redistribution of JDKs by third parties is not permitted. As a result, customers running JSPs need to download, or otherwise acquire, JDKs themselves. JVMs of different versions are supposed to be compatible with one another, but often contain different class files and libraries. Tomcat 3.3a can only run with a 1.3x JVM, and behaves erratically with a 1.4x JVM. Web Center ships with Sun's J2RE 1.3.1_07. It is not necessary to install a JDK for Web Center, since its Java Servlets are already compiled. Tomcat 4.1.29 can run with JVMs of both 1.3x and 1.4x branches. However, Interactive Forms requires libraries found only in 1.4x. Additionally, Interactive Forms is based on uncompiled JSPs, so it is necessary to separately acquire JDKs. Most Java applications locate an appropriate JVM using an environment variable called JAVA_HOME. Some Java applications use hardcoded strings to identify the appropriate JVMs. The JAVA_HOME environment variable can only be single-valued, so if multiple applications require different JVMs, but use the JAVA_HOME environment variable, then the application startup data may need to be updated. Apache HTTP Server and JK Connectors The Apache HTTP Server can be used as a frontend web server for multiple Tomcat instances. In order to do so, multiple named AJP13 workers need to be configured in the JK Connectors. StreamServe WebCenter ships with Apache HTTP Server 1.3.29 and JK 1.2.5 (mod_jk), which is compatible with both Tomcat 3.x and 4.x.

Installing two Tomcat instances on the same host 7 Installing two Tomcat instances on the same host If all the components have already been installed, skip to the next section, Identifying conflicting resources on page 7. 1 Install StreamServe Web Center, if it is not already installed, and make a note of the following: the Tomcat installation directory the JVM installation directory the value of the %JAVA_HOME% environment variable, as well as any TCP listener ports that it uses Note that the Tomcat installation directory should not contain spaces. On Windows, the netstat.exe -a -n findstr.exe LISTENING command may be helpful to determine which TCP ports are in use. 2 If the Apache HTTP server was installed, make a note of the following: the Apache HTTP server installation directory the TCP listener ports the worker configuration in the configuration of mod_jk, in particular, the names of the workers 3 Stop the Tomcat 3.x and Apache HTTP services. On Windows, from a command prompt, the net stop tomcat and net stop apache commands will accomplish this. Leaving a previous version of Tomcat running, while trying to install a new version may result in a failed installation. 4 Download and install a J2SDK 1.4.x. Make a note of the J2SDK installation directory 5 Set the %JAVA_HOME% environment variable to the new J2SDK path. 6 Download and install Tomcat 4.1.x. Make a note of the following: the Tomcat installation directory any TCP listener ports that it uses 7 Shut down the Tomcat 4.x service. On Windows you can use the net stop "Apache Tomcat 4.1" command. Identifying conflicting resources Make a chart outlining the installation directories, JVM paths, and TCP listeners for the Tomcat instances (see example in Table 1 on page 8). If any additional listeners are enabled, be sure to include them. If a frontend web server is also being used, include its information as well, to ensure that TCP listeners, such as HTTP do not overlap.

8 Installing two Tomcat instances on the same host In the chart, identify any resources that might conflict, for example: the required Java VM paths differ between Tomcat 3.x and 4.x the TCP ports for HTTP conflict: we will change the port on Tomcat 4.x the TCP ports for AJP13 conflict: we will change the port on Tomcat 4.x the AJP13 worker names conflict: we will change the name on Tomcat 4.x It is possible to modify Tomcat 3.x instead of Tomcat 4.x, or to modify both server configurations. In the following examples, only the Tomcat 4.x configuration will be modified. Table 1 Example of chart displaying conflicting resources Product Apache HTTP Server Apache Tomcat 3.x Apache Tomcat 4.x Version 1.3.29 3.3a 4.1.19 Installation directory C:\Program Files\Apache Group\Apache c:\streamservewebinte rface\jakarta-tomcat- 3.3a C:\Program Files\Apache Group\Tomcat 4.1 Java VM path N/A C:\Progra~1\Stream~1\ Direct~1\jre c:\j2sdk1.4.2_05 Java VM version N/A 1.3.1_10 1.4.2_05 TCP port for HTTP Default: 80 New: 80 Default: 8080 New: 8080 Default: 8080 New: 8081 TCP port for HTTPS Default: 443 (disabled) New: 443 (disabled) Default: 8443 (disabled) New: 8443 (disabled) Default: 8443 (disabled) New: 8443 (disabled) TCP port for admin Default: 8007 New: 8007 Default: 8005 New: 8005 Worker name AJP12 N/A Default: ajp12 New: ajp12 TCP port for AJP13 N/A Default: 8009 New: 8009 Default: 8009 New: 8010 Worker name AJP13 N/A Default: ajp13 New: ajp13 Default: ajp13 New: ajp13x Reconfiguring Tomcat 3.x with a hard-coded JVM wrapper.properties 1 Open the wrapper.properties file located in the Tomcat 3.x\conf\jk directory.

Installing two Tomcat instances on the same host 9 2 If necessary, change the wrapper.java_home value to the path of the Java 1.3 VM. The path name should contain no spaces. For example: wrapper.java_home=c:\progra~1\stream~1\direct~1\jre 3 Save and close the wrapper.properties file. tomcat.bat 1 Open the tomcat.bat file located in the Tomcat 3.x\bin directory. 2 At the end of the comment section, and before any IF... statements, insert the following two lines: setlocal set JAVA_HOME=C:\Progra~1\Stream~1\Direct~1\jre The path name should be the same as the path specified in the wrapper.properties file. 3 Save and close the tomcat.bat file. startup.bat Run the startup.bat file located in the Tomcat 3.x\bin directory. Tomcat should launch properly. Hit Control-C in the Tomcat window, or run the shutdown.bat file to shut it down. Reconfiguring Tomcat 4.x with a hard-coded JVM Open Regedit, and navigate to HKLM\SYSTEM\CurrentControlSet\Services\Apache Tomcat 4.1\Parameters\JVM Library The value should point to a server jvm.dll file within the JAVA_HOME directory, for example: c:\j2sdk1.4.2_05\jre\bin\server\jvm.dll If Tomcat 4.x was installed using the StreamServe Web Center 4.1 setup: 1 Create a new environment variable in the System Control Panel, called STRS_JAVA_HOME. STRS_JAVA_HOME overrides the value of the regular JAVA_HOME environment variable when it is present. An example environment variable setting: c:\j2sdk1.4.2_05 The value can contain spaces, but it may be safer not to use any. The environment variable is single-valued. If it contains multiple values, it will not work. If Tomcat 4.x was not installed using the StreamServe Web Center 4.1 setup: 1 Open the catalina.bat file located in the Tomcat 4.x\bin directory. 2 At the end of the comment section, insert the following line: set JAVA_HOME=c:\j2sdk1.4.2_05

10 Installing two Tomcat instances on the same host 3 Save and close the catalina.bat file. Test that Tomcat launches properly Run the startup.bat file located in the Tomcat 4.x\bin directory. Tomcat should launch properly. Hit Control-C in the Tomcat window, or run the shutdown.bat file to shut it down. Reconfiguring Tomcat 4.x with alternate TCP ports server.xml 1 Open the server.xml file located in the Tomcat 4.x\conf directory. 2 Modify the TCP port in the Coyote HTTP/1.1 Connector section (~line 90) so that it corresponds to a non-conflicting TCP port. For example: port="8081" 3 Modify the TCP port in the AJP 1.3 Connector section (~line 110) so that it corresponds to a non-conflicting TCP port. For example: port="8010" 4 Modify any additional TCP ports that conflict between the different Tomcat instances. 5 Save and close the server.xml file. startup.bat Run the startup.bat file located in the Tomcat 4.x\bin directory. Tomcat should launch properly. Hit Control-C in the Tomcat window, or run the shutdown.bat file to shut it down. Reconfiguring a frontend Apache HTTP server The Apache HTTP server can be configured as a frontend web server for multiple instances of Tomcat. In order to do so, the Apache HTTP instance must know about the JK connector, different virtual web roots, as well as the corresponding worker instances. The JK connector needs to define unique worker names and associate those with the appropriate Tomcat listeners. The following example assumes that Apache HTTP Server 1.3.x is being used in conjunction with JK (mod_jk) connector 1.2x for both Tomcat 3.x and 4.x. If another frontend web server or JK connector is being used, refer to the appropriate documentation. The overall concepts should be the same. The following example assumes that Tomcat 3.3a, Apache HTTP Server 1.3.x, and mod_jk 1.2x were installed and configured using the StreamServe WebCenter setup routine. If they were not, refer to the Tomcat 3.x mod_jk documentation first.

Installing two Tomcat instances on the same host 11 Configuring Tomcat 4.x with JK (mod_jk) 1.2x for Apache HTTP 1.3.x Tomcat 4.x was designed with JK 2.x and Apache 2.x in mind. However, it is also possible to configure it to share the JK (mod_jk) 1.2x connector with older versions of Tomcat. In order to do so, an additional Java class needs to be called from the Tomcat 4.x server.xml file. If Tomcat 4.x was installed using the StreamServe Web Center 4.1 setup routine, skip to the next section, Configuring JK Connector workers on page 11. The following instructions assume that the JK (mod_jk) 1.2x connector was installed to the Apache HTTPd directory, and that its configuration files belong in the Tomcat 3.x directory. 1 Open the server.xml file located in the Tomcat 4.x conf\ directory. 2 Somewhere after the initial <Server section, insert the following text (do not include the line breaks within lines): <!-- Configure the mod_jk Apache connector --> <Listener classname="org.apache.ajp.tomcat4.config.apacheconfig" modjk="c:/program Files/Apache Group/Apache/modules/ mod_jk.dll" workers.config="c:/streamservewebinterface/jakarta-tomcat- 3.3a/conf/jk/workers.properties" jklog="c:/streamservewebinterface/jakarta-tomcat-3.3a/ logs/mod_jk.log" /> 3 Modify the modjk value to point to the JK 1.2x connector file. There should only be one instance of the mod_jk.dll file referenced. Tomcat 3.x and 4.x should share this file if they are sharing the same Apache HTTP Server instance. If Tomcat 3.x was installed with StreamServe Web Center setup, the mod_jk file be in the Apache HTTP Server modules directory. 4 Modify the workers.config value to point to the JK Connector Workers file. Tomcat 3.x and 4.x should share this file if they are sharing the same Apache HTTP Server instance. If Tomcat 3.x was installed with StreamServe Web Center setup, the workers.properties file should be in the Tomcat 3.x/ conf/jk/ directory. 5 Modify the jklog value to point to the JK Connector's log file. 6 Save and close the server.xml file. Configuring JK Connector workers The JK Connector specifies worker threads associated with various Tomcat instances and the workers.properties file. The workers.properties file defines and assigns names to connections to Tomcat worker processes. There is one workers.properties file per JK Connector. In the following example, the one Apache HTTP server uses one JK Connector for two Tomcat instances.

12 Installing two Tomcat instances on the same host 1 Open the JK Connector workers.properties file. With a standard Tomcat 3.x installation performed through the StreamServe Web Center setup, the relevant lines in it should be as follows: worker.ajp12.port=8007 worker.ajp12.host=localhost worker.ajp12.type=ajp12 worker.ajp12.lbfactor=1 worker.ajp13.port=8009 worker.ajp13.host=localhost worker.ajp13.type=ajp13 worker.ajp13.lbfactor=1 worker.loadbalancer.balanced_workers=ajp12, ajp13 2 Identify these lines, and make sure that the port mappings are correct for the Tomcat 3.x instance, and that the hostname (e.g. localhost) does resolve to the host of the Tomcat 3.x instance. 3 After the ajp13 worker definition, copy and paste the following lines: worker.ajp13x.port=8010 worker.ajp13x.host=localhost worker.ajp13x.type=ajp13 worker.ajp13x.lbfactor=1 4 Modify the port number and hostname accordingly to point to the Tomcat 4.x instance. Note that the name of the worker (i.e. "ajp13") is part of the name of the relevant values. 5 Modify the worker.loadblancer.balanced_workers value, and insert the name of the Tomcat 4.x worker. For example: worker.loadbalancer.balanced_workers=ajp12, ajp13, ajp13x 6 Save and close the workers.properties file. Configuring Apache HTTP Server for JK (mod_jk) 1.2x Connector The Apache HTTP Server must be configured to load the JK Connector module, and then associate virtual web directories with named workers. In our example, we need to merge the configurations of two Tomcat instances. The easiest way to do this is by manually copying and pasting the contents of the two mod_jk.conf files for Tomcat 3.x and Tomcat 4.x into the httpd.conf file, rather than reference two separate files. mod_jk.conf for Tomcat 3.x If this file does not exist, the relevant contents can be generated manually. If the virtual web directories /jobgateway and /profilemanager exist in Tomcat 3.x and should be forwarded through Apache HTTPd, the mod_jk.conf file should contain something like the following (without line breaks within lines): <IfModule!mod_jk.c> LoadModule jk_module modules/mod_jk.dll </IfModule>

Installing two Tomcat instances on the same host 13 JkWorkersFile "c:/streamservewebinterface/jakarta-tomcat-3.3a/ conf/jk/workers.properties" JkLogFile "c:/streamservewebinterface/jakarta-tomcat-3.3a/logs/ mod_jk.log" JkLogLevel info JkMount /jobgateway ajp13 JkMount /jobgateway/* ajp13 JkMount /profilemanager ajp13 JkMount /profilemanager/* ajp13 mod_jk.conf for Tomcat 4.x If this file does not exist, the relevant contents can be generated manually. If the virtual web directory /iaf exists in Tomcat 4.x and should be forwarded through Apache HTTPd, the mod_jk.conf file should contain something like the following (without line breaks within lines): <IfModule!mod_jk.c> LoadModule jk_module modules/mod_jk.dll </IfModule> JkWorkersFile "c:/streamservewebinterface/jakarta-tomcat-3.3a/ conf/jk/workers.properties" JkLogFile "c:/streamservewebinterface/jakarta-tomcat-3.3a/ logs/mod_jk.log" JkLogLevel info JkMount /iaf ajp13x JkMount /iaf/* ajp13x Modified httpd.conf After modification, the data pasted into the httpd.conf file should look something like the following (without line breaks within lines): <IfModule!mod_jk.c> LoadModule jk_module modules/mod_jk.dll </IfModule> JkWorkersFile "c:/streamservewebinterface/jakarta-tomcat-3.3a/ conf/jk/workers.properties" JkLogFile "c:/streamservewebinterface/jakarta-tomcat-3.3a/ logs/mod_jk.log" JkLogLevel info JkMount /jobgateway ajp13 JkMount /jobgateway/* ajp13 JkMount /profilemanager ajp13 JkMount /profilemanager/* ajp13 JkMount /iaf ajp13x JkMount /iaf/* ajp13x

14 Installing two Tomcat instances on the same host To merge the two mod_jk.conf into the http.conf file 1 Open the httpd.conf file in the Apache HTTP Server/conf directory. If the Apache HTTP Server and the JK connector were installed by StreamServe Web Center setup, the last line should read Include "C:/StreamServeWebCenter/jakarta-tomcat-3.3a/conf/ auto/ mod_jk.conf" 2 Delete this line. 3 Open the mod_jk.conf file associated with Tomcat 3.x. 4 Open the mod_jk.conf file associated with Tomcat 4.x. 5 Copy and paste the contents of the two mod_jk.conf files into the httpd.conf file, where the Include...mod_jk.conf line used to be. 6 Remove redundant references to loading the JK module. 7 Modify paths accordingly. 8 Make sure that the names of worker threads specified here correspond to the named worker threads defined in the workers.properties file. 9 Save and close the Apache httpd.conf file.