SECTION: 700-Clustering
TITLE: modjk
QUESTION: Can Jetty be run with mod_jk?

Jetty includes <a href="/javadoc/org/mortbay/http/ajp/AJP13Listener.html">org.mortbay.http.ajp.AJP13Listener</A>, which can be
used instead of the normal SocketListener to received requests forwarded
from a mod_jk module in apache or IIS.
<P>
The AJP13Listener has been tested with mod_jk from apache and mod_jk2 from
apache2.
<P>
The <A href="http://jakarta.apache.org/tomcat/tomcat-3.3-doc/mod_jk-howto.html">normal
jakarta/apache documentation</A> 
can be used to configure mod_jk for Jetty. The documentation below was 
contributed for using mod_jk2 in apache2 and is included with the
mod_jk2 source code.

<H4>Using mod_jk2 and Jetty</H4>

<small><I>by Simon Stewart&lt;sms@lateral.net&gt;</I></small><P>

Jetty is a popular Open Source HTTP Server and Servlet container,
written in 100% pure Java. It supports serving static content,
servlets and JSPs, and is fast and lightweight. It is commonly used as
an embedded HTTP and servlet container, notably by JBoss (a full
featured J2EE environment)
<P>
Jetty's current developement branch is 4.1. This is working to enhance
the performance of the server, as well as to improve its support for
apache integration. To further this support, since 4.1.D2 Jetty has
shipped with an AJP13 connector, meaning that it can communicate using
the mod_jk and mod_jk2 apache modules in addition to working as a
standalone server. This document aims to provide a guide for using
this facility.
<P>
Normal, authenticated and SSL connections are all supported, so in
theory, Jetty could be used as a "drop in" replacement for Tomcat.
<P>
In order to keep things as simple as possible, this document only
considers apache2 and mod_jk2. This is the successor to mod_jk, and
uses the same protocol, so using the older module should not cause any
problems.
<P>
The process will be very similar to installing jk2 on any server, so
if you are using IIS or iPlanet, simply follow the normal installation
notes for jk2 on those platforms, ignoring any references to compiling
the java code. Once the native side of the AJP13 connector is
installed, skip to the section on "Configuring Jetty"


<H4>Building</H4>
<UL>
<LI> Install apache, ensuring that DSO support is available.

<LI> Install any version of Jetty from 4.1.D2 onwards.

<LI> Copy build.properties.sample to build.properties

<LI> Edit build.properties to taste. In particular it's important to set
the path to apache2.

<LI> Run "ant native" to build the native connectors for the detected
servers (both jk and jk2) It is possible to use
configure/make/dsp/apxs, but this way is simpler.

<LI> Copy the created build/apache2/mod_jk2.so to your apache
installation's module directory.
</UL>


<H4>Configuring Apache 2</H4>

On the native side, jk2 is configured using the workers2.properties
file that is kept in apache's conf directory. Currently Jetty's AJP
connector supports TCP/IP socket connections. 
<P>
Perhaps the simplest way to explain things is with an example
workers2.properties file:

<UL><PRE>
---- workers2.properties

# Example socket channel, override port and host.
[channel.socket:localhost:8009]
port=8009
host=127.0.0.1


# define the worker
[ajp13:localhost:8009]
channel=channel.socket:localhost:8009


# Uri mapping. This says that any incoming connection to any file
# under "/jetty/" should be handled the worker defined above

[uri:/jetty/*]
worker=ajp13:localhost:8009

# The same, but for /demo
[uri:/demo/*]
worker=ajp13:localhost:8009

---- end worker2.properties
</PRE></UL>


An "apachectl configtest" should report no errors. 
<P>
You should configure the URI mappings to cover any installed webapps
that you may have. The examples given here are for the demo apps that
come with a fresh download of Jetty.


<H4>Configuring Jetty</H4>

Jetty is easy to configure. At a bare minimum, all that needs to be
done is to simply include the following fragment in Jetty's
configuration file (typically found at etc/jetty.xml):

<UL><PRE>
&lt;Call name="addListener"&gt;
  &lt;Arg&gt;
    &lt;New class="org.mortbay.http.ajp.AJP13Listener"&gt;
      &lt;Set name="port"&gt;8009&lt;/Set&gt;
    &lt;/New&gt;
  &lt;/Arg&gt;
&lt;/Call&gt;
</PRE></UL>

Once this is place, it should be possible to start Jetty and then
(re)start apache. Check that everything works as expected by visiting
port 8080 of your server with a web browser. If doesn't work then you
have a problem with your Jetty config.
<P>
Assuming that you can connect properly to Jetty directly, it's time to
connect using jk2. Check that your webserver is running as expected by
pointing a browser at the homepage (for example, http://localhost/ )
If this works, attempt to visit one of the mapped URIs.
<P>
Congratulations!


<H4>Jetty Config Options</H4>

The Jetty AJP13 connector has a compact set of configuration
options. These are:

<UL><small><PRE>
---- Jetty config options

bufferSize          Size of the AJP13 data buffers 
                    (default 8192)

confidentialPort    The port to redirect to if a servlet security 
                    constraint of CONFIDENTIAL is not met. 
                    (default 0 : forbidden response).

confidentialScheme  The scheme to use for confidential redirections 
                    (default https)

host                The host or IP interface to listen on. 
                    (default 0.0.0.0 == all interfaces)

identifyListener    Set the listener name as a request attribute 
                    (default false)

lingerTimeSecs      The socket linger time for closing sockets 
                    (default 30)

maxIdleTimeMs       Millisecs that a thread can be idle before the
                    thread pool shrinks.

maxReadTimeMs       Millisecs that a read will block on a connection.

maxStopTimeMs       Millisecs to wait when gently shutting down
                    listener.

maxThreads          Maximum threads in threadpool for listener.

minThreads          Minimum threads in threadpool for listener.

name                Name of the listener.

port                Port to listen on (8009)

threadClass         The class to use for threads in the threadpool.

---- End Jetty config options
</PRE></small></UL>

Most of these default to sensible values, and some of them (such as
bufferSize) are unwise to fiddle with. An example of using these
config options is given below.

<UL><PRE>
&lt;Call name="addListener"&gt;
  &lt;Arg&gt;
    &lt;New class="org.mortbay.http.ajp.AJP13Listener"&gt;
      &lt;Set name="port"&gt;8009&lt;/Set&gt;
      &lt;Set name="minThreads"&gt;5&lt;/Set&gt;
      &lt;Set name="maxThreads"&gt;50&lt;/Set&gt;
      &lt;Set name="maxIdleTimeMs"&gt;30000&lt;/Set&gt;
      &lt;Set name="maxReadTimeMs"&gt;60000&lt;/Set&gt;
    &lt;/New&gt;
  &lt;/Arg&gt;
&lt;/Call&gt;
</PRE></UL>