Chapter 46. Migrating from mod_jk2 to mod_jk with embedded Tomcat

This document shows one of several ways to migrate mod_jk2 settings to work with mod_jk. The mod_jk2 reference setup can be found in Chapter 45 Setting Up mod_jk2 with Embedded Tomcat.

NoteNotes
 

  • All references to jonas-server should be replaced by the hostname of the target machine for which you want to configure mod_jk. Replace ${JONAS_BASE} and ${APACHE_HOME} with appropriate values.

  • Always back up files such as server.xml before editing!

46.1. Performing the Migration

  1. Make a backup copy of the $JONAS_BASE/conf/server.xml file.

  2. Edit the $JONAS_BASE/conf/server.xml file; locate and uncomment the following line:

    <!--
    <Connector port="9009"
        enableLookups="false" redirectPort="9043" debug="0"
        protocol="AJP/1.3" />
    -->

    Change it to look like this:

    <Connector port="9009"
        enableLookups="false" redirectPort="9043" debug="0"
        protocol="AJP/1.3" />
  3. Next, comment out the existing mod_jk2-oriented connector and engine elements:

    ...
    <Connector className="org.apache.coyote.tomcat5.CoyoteConnector"
        port="9009" minProcessors="5" maxProcessors="75"            
        enableLookups="true" redirectPort="9043"            
        acceptCount="10" debug="0" connectionTimeout="0"             
        useURIValidationHack="false"
        protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>

    Replace the base Engine tag in which a jvmRoute is used with the standard engine. For example, comment out the line that looks similar to the following:

    <Engine name="Tomcat-JOnAS-Engine" defaultHost="localhost" debug="0"
        jvmRoute="jonas01">

    and uncomment the following line:

    <Engine name="Tomcat-JOnAS-Engine" defaultHost="localhost" debug="0">
  4. Now you can either let tomcat generate the mod_jk.conf file automatically, which will set up forwarding for a limited set of applications, or you can create a custom mod_jk.conf file where you can specify applications to forward and customize the configuration information.

    NoteNote
     

    The automatically generated file cannot be customized because it is re-written every time the user restarts tomcat.

    1. To enable automatic generation, insert the following into the server.xml file nested under the base <Server> tag:

      <Listener className="org.apache.jk.config.ApacheConfig"
          modJk="$APACHE_HOME/modules/mod_jk.so" />

      and insert the following under the <Host> element:

      <Listener className="org.apache.jk.config.ApacheConfig"
          append="true" forwardAll="false"
          modJk="$APACHE_HOME/modules/mod_jk.so"/>

      When jonas/tomcat is restarted, there will be a file created under $JONAS_BASE/lib/catalina/conf/auto called mod_jk.conf.

    2. If you want to create a custom file, place a file named mod_jk.conf under $JONAS_BASE/conf/jk. This file is the equivalent of the $APACHE_HOME/conf.d/JOnAS.conf in the mod_jk2 directions; however, it is not a direct replacement.

      A simple mod_jk.conf file that can be used is:

      # Load the mod_jk module if not loaded.
      <IfModule !mod_jk.c>
      LoadModule jk_module "$APACHE_HOME/modules/mod_jk.so"
      </IfModule>
      
      # Specify location of worker file and log file.
      # Worker file will follow shortly.
      JkWorkersFile "$JONAS_BASE/conf/jk/workers.properties"
      JkLogFile "$JONAS_BASE/logs/mod_jk.log"
      
      # When and how much logging.
      JkLogLevel emerg
      
      # This is a little awkward. It seems mod_jk associates 
      # applications it will map to tomcat based on the virtual host. 
      # If for instance I wish to visit the jonasAdmin application 
      # through http://jonas-server/jonasAdmin from another machine 
      # and I have the following setting then the application behaves
      # perfectly normally, that is, behaves as one would expect if you
      # were using the application directly using the appropriate 
      # port (9000).
      # However, if you try using http://localhost/jonasAdmin from 
      # jonas-server without the explicit VirtualHost declaration, 
      # only the directory contents are mapped. No processing on tomcat 
      # is carried out, so struts-based applications will fail to work. 
      # That is the reason why we explicitly mention both virtual hosts.
      <VirtualHost jonas-server>
          ServerName jonas-server
          JkMount /cmp2 ajp13
          JkMount /cmp2/* ajp13
          JkMount /alarm ajp13
          JkMount /alarm/* ajp1
          JkMount /earsample ajp13
          JkMount /earsample/* ajp13
          JkMount /jonasAdmin ajp13
          JkMount /jonasAdmin/* ajp13
      </VirtualHost>
      
      <VirtualHost localhost>
          ServerName localhost
          JkMount /cmp2 ajp13
          JkMount /cmp2/* ajp13
          JkMount /alarm ajp13
          JkMount /alarm/* ajp13
          JkMount /earsample ajp13
          JkMount /ears!
          mple/* ajp13
          JkMount /jonasAdmin ajp13
          JkMount /jonasAdmin/* ajp13
      </VirtualHost>
    3. Now tell apache to use this file. Back up the $APACHE_HOME/conf/httpd.conf file. Edit the /etc/httpd/conf/httpd.conf file and insert:

      Include ${JONAS_BASE}/conf/jk/mod_jk.conf

      NoteNote
       

      Replace ${JONAS_BASE} with the appropriate value.

      Locate and comment-out the following line in the same file:

      LoadModule jk2_module modules/mod_jk2.so
    4. Now create a workers.properties file. This can be placed in $JONAS_BASE/conf/jk/workers.properties. A sample that has been used successfully is:

      # workers.java_home should point to your Java installation. 
      # Normally you should have a bin and lib directories beneath it.
      #
      workers.java_home=/usr/lib/jvm/java
      
      #
      # You should configure your environment slash... ps=\ on NT 
      # and / on UNIX and maybe something different elsewhere.
      #
      ps=/
      
      #
      #------ ADVANCED MODE ----------------------------------------
      #-------------------------------------------------------------
      #
      
      #
      #------ DEFAULT worker list ----------------------------------
      #-------------------------------------------------------------
      #
      #
      # The workers that your plugins should create and work with
      #
      # Add 'inprocess' if you want a JNI connector
      worker.list=ajp13
      # , inprocess
      
      
      #
      #------ DEFAULT worker1 WORKER DEFINITION --------------------
      #-------------------------------------------------------------
      #
      
      #
      # Defining a worker named worker1 and of type worker1
      # Note that the name and the type do not have to match.
      #
      worker.ajp13.port=9009
      worker.ajp13.host=jonas-server
      worker.ajp13.type=ajp13
      
      
      #----------------------------------------------------------
    5. Once all this is completed, restart jonas, then httpd.

    6. Follow that up with a quick test by visiting: http://${HOSTNAME}/jonasAdmin

      You should be able to use the application as normal. You can now also use cmp2, earsample, alarm and jonasAdmin using mod_jk instead.