3. Serving QueueMetrics through Apache

Prev		Next

You may want to serve QueueMetrics through an Apache front-end instead of using Tomcat natively. This is useful if:

You require better efficiency, so that static files are served natively without passing through Tomcat
You need to integrate Qm on a virtual server that offers other services, e.g. applications written in PHP/Perl/CGI
You need to serve QM on the public internet and want to use the security tools Apache offers.

3.1. Prerequisites

A working QueueMetrics instance
Apache 2.0 installed, with headers and compilation tools

3.2. Installing mod_jk

Download ’mod_jk’ from the Apache Tomcat website; it will be in a file named e.g ’jakarta-tomcat-connectors-jk-1.2-src-current.tar.gz’ .

Run the following commands:

tar zxvf jakarta-tomcat-connectors-jk-1.2-src-current.tar.gz
cd jk/native

Check where the ’apxs’ command is by running ’locate apxs’. Default location is ’/usr/sbin/apxs’.

Check that $CATALINA_HOME and $JAVA_HOME are defined; default values are ’/usr/local/queuemetrics/tomcat’ and ’/usr/local/queuemetrics/java’ respectively.

Configure ’mod_jk’ by running

./configure \
    --with-apxs=/usr/sbin/apxs \
    --with-tomcat41=$CATALINA_HOME \
    --with-java-home=$JAVA_HOME \
    --with-jni

make
make install

This will build mod_jk and install it as an Apache module

3.3. Configuration of Apache and mod_jk

Add the following lines to ’/etc/http/conf/httpd.conf’. Check for paths to be correct.

#-------------------------------------------------------
#                      t o m c a t
#-------------------------------------------------------

# Load mod_jk module
LoadModule jk_module modules/mod_jk.so

# Where to find workers.properties
JkWorkersFile /etc/httpd/conf/workers.properties

# Where to put jk logs
JkLogFile /var/log/httpd/mod_jk.log
JkLogLevel info
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "

# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat +ForwardDirectories

# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"

# Send everything for context /examples to worker named worker1 (ajp13)
# JkMount /examples/* worker1
# JkMount /* worker1

We comment out JkMount lines because we will define them at the virtual host level.

Configure workers by creating the file ’/etc/httpd/conf/workers.properties’:

# Define 1 real worker using ajp13
 worker.list=worker1

# Set properties for worker1 (ajp13)
 worker.worker1.type=ajp13
 worker.worker1.host=localhost
 worker.worker1.port=8009
 worker.worker1.lbfactor=50
 worker.worker1.cachesize=10
 worker.worker1.cache_timeout=600
 worker.worker1.socket_keepalive=1
 worker.worker1.socket_timeout=300

Each worker is a Tomcat instance; you can define more than one if you run multiple webapps each in their own Virtual Machine, for maximum security.

3.4. Virtual host configuration

Check the following lines in ’httpd.conf’:

Listen 80
NameVirtualHost *

Add the following lines for each Virtual Host you want to support:

<VirtualHost *>
    ServerName queuemetrics.example.com
    ServerAdmin webmaster@example.com
    DocumentRoot /var/www/virtualhost/example.com/queuemetrics
    CustomLog /var/log/httpd/queuemetrics.example.com_access.log common
    ErrorLog /var/log/httpd/queuemetrics.example.com_error.log
    JkMount /*.jsp worker1
    JkMount /*.do worker1
    JkMount /tpf worker1
    JkMount /manager/* worker1
</VirtualHost>

You can include or exclude the ’/manager’ path in order to access Tomcat’s manager.

3.5. Creating Virtualhosts in Tomcat

3.5.1. Turning off unnecessary connectors

Within Tomcat’s ’server.xml’ file, within the section marked by ’SERVICE NAME=Catalina’, remove all connector entries but the one here:

<!-- Define a Coyote/JK2 AJP 1.3 Connector on port 8009 -->
    <Connector port="8009"
               enableLookups="false" redirectPort="8443" debug="0"
               protocol="AJP/1.3" />

This is the access point for Apache. This port should be unreachable outside this box.

3.5.2. Enabling the virtual host

By the end of ’server.xml’, after the default virtual host (section ’<Host>…</Host>’) add an entry like:

<Host name="queuemetrics.example.com"  debug="0"
        appBase="/var/www/virtualhost/example.com/queuemetrics"
        unpackWARs="true">
        <Alias>qm2.example.com</Alias>

        <Logger className="org.apache.catalina.logger.FileLogger"
                directory="/var/log/httpd"
                prefix="queuemetrics.example.com_tomcat-" suffix=".log"
           timestamp="false"/>

        <Context path="" docBase="" debug="0" reloadable="true"/>

   <Context path="/manager" debug="0" privileged="true"
       docBase="/usr/local/queuemetrics/tomcat/webapps/manager">
   </Context>
</Host>

If you want the manager webapp to be available, you need to include the context path as in the example above (check the path to be correct).

Restart everything.

/etc/init.d/httpd restart
/etc/init.d/queuemetrics restart

Check the logs when restarting. Go to http://queuemetrics.example.com/queuemetrics and check that QueueMetrics is working.

3.6. Troubleshooting

If you see lines like these appear on ’catalina.out’:

org.apache.jk.common.HandlerRequest decodeRequest
WARNING: Error registering request

You need to locate the file ’jk2.properties’ and add/edit the following line:

request.registerRequests=false

CAUTION: This change must be made when Tomcat is stopped, or it will overwrite it when it terminates.