This document explains how to connect Tomcat to the popular
open source web server, Apache. It was originally part of
Tomcat: A Minimalistic User's Guide by Gal Shachor, but
has been split off for organizational reasons. It should be
considered a work in progress. Since the Tomcat source
tree is constantly changing, the information herein may be out
of date. The only definitive reference at this point is the source
code.
Other important documents:
Table of Contents
As stated in the Tomcat User's Guide,
Tomcat currently supports three
modes of execution. While it is entirely possible to have
Tomcat serve both your static and dynamic document provision needs, there
are several reasons why you might not want want to do this.
With respect to the Apache web server,
1. Tomcat is not as fast as Apache when it comes to static pages.
2. Tomcat is not as configurable as Apache.
3. Tomcat is not as robust as Apache.
4. Tomcat may not address many
sites' need for functionality found only in Apache modules (e.g. Perl,
PHP, etc.).
For all these reasons it is recommended that real-world sites use an
industrial-strength web server, such as Apache, for serving static
content, and use Tomcat as a Servlet/JSP add-on.
In a nutshell a web server is waiting for requests. When
these requests arrive the server does whatever is needed to
serve the requests by providing the necessary content. Adding
Tomcat to the mix may somewhat change this behavior. Now the web
server needs to perform the following:
- Before the first request can be served, Apache needs to load a web
server adapter library (so Tomcat can communicate with Apache)
and initialize it.
- When a request arrives, Apache needs to check and see if it
belongs to a servlet; if so it needs to let the adapter
take the request and handle it.
We'd like Apache to handle our static content, such as
images and HTML documents, and forward all requests for
dynamic content to Tomcat. More specifically, we need answers to the following questions:
1. How will Apache know which request / type of
requests should be forwarded to Tomcat?
2. How will Apache forward these requests to
Tomcat?
3. How will Tomcat accept and handle these requests?
The majority of our time will be spent dealing with points 1 and 2;
3 should be a snap!
Answers to the above three questions!
1. Modify Apache's httpd.conf file.
2. Install a web server adapter.
3. Modify Tomcat's server.xml file.
It is assumed that you are comfortable modifying the configuration of Tomcat
and Apache separately before you've attempted to integrate the
two. As such, we speak in Tomcat/Apache/Servlet lingo, not pausing
to explain what's already been taught in their respective user
guides. Details on Tomcat setup can be found in the Tomcat
User's Guide, while Apache configuration information can be found in
the Apache User's Guide.
Throughout this document, we'll refer back to these examples,
as these run the gambit of the commonly-desired Apache installs.
Non-virtual Hosts
1. All JSP and Servlet
requests consisting of http://localhost/
are sent to the "rootExample" Context.
2. All JSP and Servlet
requests consisting of http://localhost/subdirExample/
are sent to the "slifkaExample" Context.
Virtual Hosts
3. All JSP and Servlet
requests consisting of http://virtualhost/
are sent to "vhostExample" Context.
4. All JSP and Servlet
requests consisting of http://virtualhost/vhostSubdir/
are sent to the "vhostSubdir" Context.
As part of all of these configurations, servlets will be mounted as
well. To reach a servlet registered via a particular Context's
WEB-INF/web.xml file, we'll configure
it so that appending /servlet/registeredServletName to the URL does the
trick. For Example (2), let's say we had the
following as part of our web.xml for this context:
<servlet>
<servlet-name>SlifkaWorld</servlet-name>
<servlet-class>foo.bar.baz.SomeClass</servlet-class>
<init-param>
<param-name>someParameter</param-name>
<param-value>A value</param-value>
</init-param>
</servlet>
To reach this servlet, we would request: http://localhost/subdirExample/servlet/SlifkaWorld
If you're unsure as to what web.xml, Contexts, servlets, or webapps are,
then you probably haven't read through the Tomcat User's
Guide. Get to it!
We can configure Tomcat independantly of the other two items on our to-do
list. At this point,
we're assuming that you've followed the directions in the User's
Guide and have Tomcat up and running in stand-alone
mode.
First off, let's explicitly define our example Contexts in Tomcat's server.xml.
The numbers preceding each configuration snippet refer to the
aforementioned Running Examples.
1. <Context path="/"
docBase="webapps/rootExample"/>
2. <Context path="/slifkaExample"
docBase="webapps/slifkaExample"/>
Example (3) must be placed inside a <Host> element in server.xml.
This is because a <Context> with the same path attribute exists
already; Example (1) is located at "/" as is (3). We place (4)
inside the <Host> element as well, because we only want it to be
accessible when people specify this virtual host in the
request. For more information on the <Host>
element, see the server.xml section of the User's Guide, and the Virtual
Hosting section below.
Remember
to omit the numbers 3 and 4 if you plan on pasting this in!
<Host name="fully-qualified name or IP of the
virtual host">
3. <Context path="/"
docBase="webapps/vhostExample"/>
4. <Context path="/vhostSubdir"
docBase="webapps/vhostSubdir"/>
</Host>
After you've made the appropriate changes to server.xml, remember to
restart Tomcat.
Where do we stand now? So
far it's just a normal Tomcat install, which you should be well-familiar
with by now from the User's Guide. Tomcat should be serving all the
documents, both static and dynamic, for all of your Contexts. An
easy way to see which Contexts are serving which requests is to watch
your Tomcat log output, either via stdout/err or the log file.
Before we leave this section, there's one more Tomcat aspect to
discuss, the AJP <Connector> element in server.xml. This is
the mechanism by which Tomcat will communicate with Apache.
<!-- Apache AJP12 support. This is also used to shut down tomcat.
-->
<Connector
className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
<Parameter name="port"
value="8007"/>
</Connector>
To ensure that it is indeed listening on that port, Telnet to it or
HTTP request it. The Ajp12ConnectionHandler will throw an
exception (visible in the tomcat log file), and you'll know it's listening. As far as the web
server adapter goes, this is all you really need to know on the Tomcat
side for now.
Tomcat also supports AJP v1.3 via the Ajp13ConnectionHandler.
We'll get to this when we discuss mod_jk and mod_jserv later on.
The next step in integrating Apache with Tomcat is to install a web
server adapter. This is the piece of software that will relay
information between Tomcat and Apache.
It doesn't really belong under Apache configuration, and it doesn't
really belong under Tomcat configuration, but it's required for both of them
to work together.
The web server adapter answers question 2 posed above,
"How will Apache forward these requests to
Tomcat?"
Currently there are two adapters available - jk and JServ.
Taken from our, "mod_jk HOWTO",
mod_jk is a replacement to the elderly mod_jserv. It is a completely new
Tomcat-Apache plugin that passed adaptation to Tomcat. With some luck, working
with it is going to be simpler for everyone. Here are some things to
consider:
- mod_jserv was too complex
because it supported JServ specific requirements that Tomcat does not
pose.
- mod_jserv supported only
Apache; on the other hand Tomcat supports many web servers through a
compatibility layer named the jk library. Supporting two different modes
of work became problematic in terms of support, documentation and bug
fixes. mod_jk should fix that.
- The layered approach provided
by the jk library makes it easier to support both Apache1.3.x and
Apache2.xx.
- mod_jserv only supports AJP v1.2. JServ is feature complete, and
won't be enhanced aside from bug fixes.
- mod_jk supports
- AJP v1.3 - reuse the TCP connection between Apache and Tomcat, much
faster.
- JNI - the fastest if you have a multithreaded server like Apache 2.0.
Binaries are available for Linux and Win32 under the bin directory where
you obtained the Tomcat distribution file. For Linux, JServ is available
as mod_jserv.so and Jk is available as mod_jk.so. For Win32, JServ is
available as ApacheModuleJServ.dll and Jk is available as mod_jk.dll.
For UNIX, JServ and Jk must be build from source. Source is available
as part of the Tomcat source distribution. JServ source is found in the
src/native/apache/jServ directory, which contains make files for UNIX and
Win32. Jk source is found in src/native/jk plus src/native/apache1.3 or
src/native/apache2.0 depending on which Apache is the target. Jk make files
for FreeBSD, Linux, Netware, and Win32 (as a Visual C++ 6 project file)
are found in the apache1.3 and apache2.0 directories.
The make files for JServ contain a small amount of documentation within.
A little more can be found in
User's Guide. What we have below serves as a brief treatment of
the mod_jk build steps for Win32 and *nix. This is by no means meant
to be a complete treatment of the build process in all environments, just a
quick hit to get you started.
Win32 (an excerpt from our mod_jk HOWTO):
The redirector was developed using Visual C++ Ver.6.0, so having this
environment is a prereq if you want to perform a custom build. The steps that you need to take are:
- Change to the desired Apache (as explained above) source directory.
- Set an APACHE1_HOME environment variable which points to where your Apache is
installed.
- Execute the following
command:
MSDEV mod_jk.dsp /MAKE ALL
NOTE: If msdev is not in your path, enter the full path to msdev.exe. Also, ApacheCore.lib
is expected to exist in the APACHE1_HOME"src"CoreD and APACHE1_HOME"src"CoreR
directories before linking will succeed. You will need to build enough of the
Apache source to create these libraries.
- Copy mod_jk.dll to Apache's modules directory.
This will build both release and debug versions of the redirector plugin (mod_jk).
An alternative will be to open mod_jk.dsp in msdev and build it using the build
menu.
UNIX:
- Change to the desired Apache (as explained above) source directory.
- Set the environment variable $APACHE_HOME to the root of the Apache source
tree.
- Execute the following command:
./build.sh
That's it!
The effects we're concerned with relate to the different
Apache directives each adapter makes available to us. Conceptually, we'll be
adding Apache directives to get the same job done, but depending on which
adapter you've chosen, they will differ. We will take both
adapters into consideration while explaining the Apache configuration in
subsequent sections.
Now that we've answered questions (2) and (3),
we're ready to dive into question (1) - Apache itself. We need to tell
Apache how to load and initialize our adapter, and that certain requests should be handled by
this adapter and
forwarded onto Tomcat. Which requests depends on your
configuration. Surprisingly enough, this part can be just as simple as
the previous two, considering that (surprise!) Tomcat does most of the work
for you.
Each time you start Tomcat, after it loads Contexts (both from the
server.xml and automatically from $TOMCAT_HOME/webapps), it automagically
generates a number of files for you. The two that we're concerned with
are:
- tomcat-apache.conf (should really be named mod_jserv.conf-auto)
- mod_jk.conf-auto
Both of these files do exactly what we want - supplement Apache's
httpd.conf file with the directives necessary to have Apache (Tomcat) serve
our static (dynamic) content needs. We'll be examining each file in
the coming sections. For many users, directly including one of these files in httpd.conf,
depending on the adapter you're using, suffices. For example, if
you're using mod_jk (which we suggest!), you would insert the following:
include /tomcat/conf/mod_jk.conf-auto
...of course substituting in the directory you've installed Tomcat into,
in place of /tomcat. NOTE: These files are generated each time Tomcat
starts, and a Tomcat configuration change affecting whichever file you're
including necessitates
an Apache restart. If you plan on customizing this file, do it
elsewhere, as it is overwritten at each restart.
For now, refer to the comments in the mod_jk.conf-auto file and
mod_jk HOWTO for details.
This isn't nearly as verbose as the
mod_jk file, and is therefore a bit trickier to read through. What
you will see below is a condensed version of the .conf file generated from a server.xml
containing our Running Examples. To
aid in our explanation of the file's contents, we've inserted comments
directly, and funked with the formatting.
Before we get started, there is one JServ directive used extensively
that you should know about: ApJServMount. ApJServMount has the
following syntax:
ApJServMount <URI> <Tomcat process location and context in URI
format (relative or full)>
In English, this says, "Any request that starts with <URI>
should be passed on to <Tomcat process location and context> for
execution." Don't worry if it's not quite clear yet, examples
follow!
This file has been modified quite a bit as the auto-generated one doesn't do
exactly what we want, and isn't laden with comments :-) but it comes pretty close! With the knowledge
gained thus far, this shouldn't be too much of a leap, so here goes:
Apache-Tomcat Configuration where Apache Serves the Static Content
#######################################################
#
# BEGIN JServ Configuration
#
# Step (1) - See description following this sample file
LoadModule jserv_module libexec/mod_jserv.so
<IfModule mod_jserv.c>
# Step (2) - See description following this sample file
ApJServManual on
ApJServSecretKey DISABLED
ApJServMountCopy on
ApJServLogLevel notice
# Step (3) - See description following this sample file
ApJServDefaultProtocol ajpv12
ApJServDefaultPort 8007
# ADDED THIS LAST ONE MANUALLY - ed.
ApJServDefaultHost localhost
#
# END JServ Configuration
#
#######################################################
# The following two lines register the JSP type with
# Apache and instruct it to have all JSP requests
# handled by the jserv-servlet handler.
AddType text/jsp .jsp
AddHandler jserv-servlet .jsp
# WAS: ApJServMount /servlet /ROOT
# WHY: We changed it because we want to explicitly state
# that all requests to /servlet are sent to our
# "/rootExample" context in Tomcat. See the details
# of Example (1) above for more information.
ApJServMount /servlet /rootExample
#######################################################
#
# Step (4) - BEGIN Example (1) Configuration
#
# Step (4a)
# WAS: Alias /rootExample "/home/rslifka/tomcat/webapps/rootExample"
# WHY: Why did we remove it? Well, this was here so that requests
# to http://localhost/rootExample would serve the right
# static documents. Unfortunately, we wanted our application residing
# at the root of the server, and not under the /rootExample directory.
#
# The DocumentRoot should be set instead.
DocumentRoot /home/rslifka/tomcat/webapps/rootExample
# Step (4b)
# WHY: Just like a regular Apache setup, we're setting some
# traits of how we'd like requests handled. See the Apache
# documentation for more detail than you could ever want. ;)
# This particular setup leaves directory indices on, which
# most people turn off. To do that, you'd use the uncommented
# line in the middle of the <Directory> element.
<Directory "/home/rslifka/tomcat/webapps/rootExample">
Options Indexes FollowSymLinks
# Options -Indexes
</Directory>
# Step 4(c)
# WAS: ApJServMount /rootExample/servlet /rootExample
# WHY: Why did we remove it? Because we remapped the first
# ApJServMount further up, before the configuration for
# this context.
# Step 4(d)
# WHY: As per the servlet spec, nothing under WEB-INF should
# be viewable since that's where all your gold (web.xml, etc.) is.
# See the User's Guide and servlet spec for more information on
# the application hierarchy.
<Location "/home/rslifka/tomcat/webapps/rootExample/WEB-INF/">
AllowOverride None
deny from all
</Location>
#
# END Example(1) Configuration
#
#######################################################
#######################################################
#
# Step (5) - BEGIN Example (2) Configuration
#
Alias /subdirExample /home/rslifka/tomcat/webapps/slifkaExample
ApJServMount /subdirExample/servlet /slifkaExample
<Location "/home/rslifka/tomcat/webapps/slifkaExample/WEB-INF/">
AllowOverride None
deny from all
</Location>
<Directory "/home/rslifka/tomcat/webapps/slifkaExample">
Options Indexes FollowSymLinks
</Directory>
#
# END Example(2) Configuration
#
#######################################################
</IfModule>
|
All of the above directives, with the exception of anything prefixed
by "ApJServ" are extensively documented in the Apache
User's Guide. If you find our coverage brief, please look
there for the desired information.
Below, we go into further detail about each commented step:
1. Instruct Apache to load the jserv
shared-object (or the NT world dll).
If the loading went well and the module came from a file named
mod_jserv.c (1a) we can start with the rest of the configuration.
2. This step sets various JServ internal
parameters, in order:
- Instruct JServ not to start the Tomcat process. Automatically
starting Tomcat is not implemented yet.
- Disable the secret key challenge/response between Apache and Tomcat.
Again, the secret key work is not implemented yet.
- Instruct JServ to copy the base server mount points (see next
section) in case of virtual hosting.
- Instruct JServ to use the notice log level. Other log levels
include emerg, alert, crit, error, warn, info and debug.
3. This step sets JServ's default communication
parameters.
It
says that the default protocol used for the communication is ajpv12 (do
not mess with this one) and that the Tomcat process runs on the same
machine and listens on port 8007. If you run Tomcat on a machine other
than the one used for Apache you should either update your
ApJServDefaultHost or use a full URL when mounting contexts (see next).
Also, if you configured the Tomcat connectors to use a port other then
8007, you should update your ApJServDefaultPort or use a full URL when
mounting contexts.
4. These steps "register" (for lack of
a better word) our Example (1) context
w/Apache.
Most everything is explained up inside the example, but there
are a few things you should know. The first is that, as you
can see, contexts mounted at the root of your web (e.g. http://localhost/
versus http://localhost/myApp)
server require a little more work than they would otherwise.
Second, don't take anything auto-generated for granted. It's a
very nice feature and works in many, many cases. Still though,
you're setting up two complicated pieces of software and should
probably be familiar with what it all means and why/how it all
works! Tomcat has no way of knowing how you're going to
"register" the context in Apache, and does its best to
guess.
5. These steps register our Example
(2) context w/Apache.
There are two differences between Example (1) and Example (2)'s
setup. First, since the DocumentRoot is already defined and
mounted to our rootExample content (Example (1)), we use an Alias to
tell Apache how to serve up our static documents. Second, we
modify the ApJServMount directive to reflect the path that the
context resides in (/subdirExample).
Your configuration is complete! All you have to do now is
restart Apache, and you're cooking with gas.
Sometimes it is useful to have different contexts handled by
different JVMs, for example:
- When each context serves a different, specific task and runs
on a different machine.
- When we want to have multiple developers work on a private
Tomcat process but use the same web server.
Implementing such schemes where different contexts are served by different
JVMs is very easy and the following configuration file demonstrates this:
Here's where we have to step back to Tomcat. First, you
have to be running two separate instances of Tomcat, hence the "mutliple
JVMs". Of course, each instance of Tomcat will need its web
adapter Connector listening on a unique port. You'll remember the
following snippet from server.xml in our AJP section:
<!-- Apache AJP12 support. This is also used to shut down tomcat.
--<
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
<Parameter name="port"
value="8007"/>
</Connector>
The key here is that each port parameter's "value"
attribute must have a different value. To keep in sync, let's
pretend that our Example (1) has its own
instance of Tomcat, as does Example (2).
Example(1)'s port is 8007 and Example (2)'s port is 8009; they are both
running on the localhost.
NOTE: There are other changes required to run multiple instances
of Tomcat (e.g. specifying different logging directories). Those changes and more are covered in the User's
Guide.
We've snipped out the irrelevant sections (at least to this example)
of the .conf file. The only change(s) you need to make, is to be a
bit more specific when instructing the web server adapter on how to find the Tomcat process
responsible for your context.
Apache-Tomcat Configuration with per Context JVM
[ snip! ]
# Mounting Example (1)
ApJServMount /servlet ajpv12://localhost:8007/rootExample
# Mounting Example (2)
ApJServMount /subdirExample/servlet ajpv12://localhost:8009/slifkaExample
[ snip! ]
|
As you can see, the key to integrating multiple instances with Apache
is to specify the full URL when mounting via the ApJServMount
directive. This is how you're able to tell JServ that the Tomcat
processes are each listening on separate ports. If the Tomcat
instances were running on separate machines, you would change the "localhost"
to the appropriate machine name in the ApJServMount directive(s).
NOTE:
Your $TOMCAT_HOME/conf/tomcat-apache.conf file is overwritten each time
you restart Tomcat. This configuration requires a custom tomcat-apache.conf,
so making your changes to, and subsequently including, one of the
auto-generated ones is a *bad idea*. Your changes will be
overwritten each time Tomcat restarts.
Once you've got Apache configured correctly with the <VirtualHost>
entries (discussed in part below), getting virtual hosting working under Tomcat isn't that difficult.
There are two ways achieving this:
- Use a different Tomcat port (and therefore multiple
instances of Tomcat) between Apache and Tomcat per virtual
host.
- Advantages
- Works in Tomcat 3.1 and 3.2
- Because it sends calls for different Virtual Hosts to
different Tomcat JVMs, this can be used to spread the load over
several machines
- Development can occur in isolation (an instance per developer)
but still use the same machine, and same overall installation of
Tomcat
- Disadvantages
- Doesn't scale well (an instance of Tomcat per virtual host is
required)
- Difficult to maintain for more than
a few hosts (requires a different server.xml for each virtual
host)
- Use the <Host> directive in Tomcats' server.xml file
- Advantages
- Easier to set up
- Uses less system resources => scales much better (only one
Tomcat instance, single adapter connector port)
- Disadvantages
- Only works under Tomcat 3.2
- If Tomcat needs to be restarted for one virtual host, it needs
to be restarted for all of them
To set up Apache and Tomcat using the first method, you need to set up a
different ports for Apache and Tomcat to communicate for each host. Here's a
sample Apache configuration (which uses mod_jserv):
Option 1 - Different Tomcat for each Apache Virtual Host
[ snip! ]
# Mount Example (3)s virtual host
<VirtualHost 9.148.16.139>
ServerName www.virtualhost.com
DocumentRoot path-to-your-docbase
ApJServMount /servlet ajpv12://localhost:8007/vhostExample
</VirtualHost>
# Mount Example (4)s virtual host
<VirtualHost 9.148.16.139>
ServerName www.virtualhost.com
ApJServMount /servlet ajpv12://localhost:8009/examples
DocumentRoot path-to-your-docbase
</VirtualHost>
[ snip! ]
|
NOTE: Remember to set the DocumentRoot so Apache knows where to
serve the static files from. In our mod_jserv and mod_jk examples,
this was done by specifying an Alias since the DocumentRoot was already
defined. Keep in mind that the ApJServMount is relative from the
DocumentRoot. What's a DocumentRoot and what's an Alias? See the Apache
User's Guide!
As you can see from the above example, using Tomcat in a virtual hosting environment isn't that different
insofar as Apache is concerned. Of course, you'll need to setup
the appropriate <VirtualHost> entries, but other than
that, there isn't much difference. Inside each virtual host entry,
you have all of your context-specific information in the usual way, and
that's it really.
Here is an example setup for a machine serving virtual hosts using the
second method described above.
Option 2 - Same Tomcat for all Virtual Hosts (httpd.conf)
[ snip! ]
# Minimalistic Virtual Host configuration
<VirtualHost 192.168.0.1>
ServerName host1
DocumentRoot /web/host1/html
ApJServMount /servlet /ROOT
<Directory "/web/host1/html/WEB-INF">
Options None
Deny from all
</Directory>
</VirtualHost>
<VirtualHost 192.168.0.1>
ServerName host2
DocumentRoot /web/host2/html
ApJServMount /servlet /ROOT
<Directory "/web/host2/html/WEB-INF">
Options None
Deny from all
</Directory>
</VirtualHost>
[ snip! ]
|
This creates two virtual hosts, host1 and host2, both running off of the
same IP - 192.168.0.1. Any requests for paths beginning with
"/servlet" are passed to Tomcat for processing, as are JSP
requests, providing of course that you've added the aforementioned
AddType and AddHandler directives.
Next, you need to configure Tomcat's server.xml file.
Option 2 - Same Tomcat for all Virtual Hosts (server.xml)
[ snip! ]
# Minimalistic Virtual Host configuration
<VirtualHost 192.168.0.1>
ServerName host1
DocumentRoot /web/host1/html
ApJServMount /servlet /ROOT
<Directory "/web/host1/html/WEB-INF">
Options None
Deny from all
</Directory>
</VirtualHost>
<VirtualHost 192.168.0.1>
ServerName host2
DocumentRoot /web/host2/html
ApJServMount /servlet /ROOT
<Directory "/web/host2/html/WEB-INF">
Options None
Deny from all
</Directory>
</VirtualHost>
[ snip! ]
|
That's it! Place your servlets in the WEB-INF/classes directory
for each virtual host, restart Tomcat and Apache, and you should be
away. If not, be sure to check the Common
Problems section.
This section isn't meant to be your one-stop shop for all troubles
Tomcat-Apache, but a resource for stumbling blocks common to many first-time
Tomcat'ers. See the help section
of the User's Guide for
additional links.
One thing that many users don't recall is that there is a
wealth of information to be found in the log files! Primarily, the tomcat.log
file in your $TOMCAT_HOME/logs directory, or wherever you've configured
it. If you want more detail, see the User's Guide for instructions
on how to edit your server.xml to have more verbose logging.
In addition, the web server adapter has a log file as well. It's
usually <adapter_name>.log (e.g. mod_jserv.log).
If this occurs, you should see a stack trace in your tomcat.log file, starting with:
HANDLER THREAD PROBLEM: java.io.IOException: Stream broken
By default, Tomcat listens for AJP connections on port 8007. AJP
is a protocol used to communicate between the web server and Tomcat, not
Tomcat and your browser. Many first-time users mistakenly assume
that this is how you test your Tomcat installation or Tomcat-Apache
integration, while this is not the case.
This most likely means that Tomcat is trying to use a port that is
already being used by someone else - usually Apache or another instance of
Tomcat. By default, Tomcat's comes configured to run an HTTP server on port
8080. If you examine the supplied server.xml file, you'll see the
following element:
<!-- Normal HTTP -->
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
<Parameter name="port"
value="8080"/>
</Connector>
To disable this, just comment out the entire <Connector>
element. Otherwise, just change it to a port that doesn't conflict
with Apache. If you're not going to use the Tomcat HTTP server, and
you probably won't be if you are reading this document, disable it.
If you're running Apache / JServ, JServ may be clashing with Tomcat on
port 8007 as well.
Apparently you can, but you'll need to use mod_jserv rather than mod_jk.
As of Tomcat 3.2b2, the mod_jserv.so is the same as that used by
Apache/JServ. You will need to run Apache/JServ on a different port
to Tomcat, then you can control which servlet engine/container handles
which requests by specifying the appropriate port via the ApJServMount
directive in Apache's httpd.conf.
Apache forwards all requests underneath a mounting to Tomcat.
Let's say you had the following at the root-level of your httpd.conf
file. You're thinking, "I'll forward all JSP and Servlet
requests to Tomcat". What Apache thinks is, "I'll forward
EVERYTHING to Tomcat":
Counter-intuitive Tomcat-Apache configuration
[ snip! ]
# OOPS! - Forward everything to Tomcat
ApJServMount / ajpv12://myTomcatHost:1234/blah
# Do not show directory indicies
<Directory "/home/myApp">
AllowOverride AuthConfig
Options -Indexes
</Directory>
# Block WEB-INF from all viewing
<Location "/home/myApp/WEB-INF/">
AllowOverride None
deny from all
</Location>
[ snip! ]
|
What's happened here is that the first ApJServMount is saying,
"Anything under the root '/' should be forwarded to the following
Tomcat process/path for handling." This results in requests for
static documents being forwarded as well, which isn't what we want.
If I was told to 'fix' the above conf file, I would just change the '/'
after ApJServMount to "/servlet". You would have
already defined earlier up that all JSP requests go to the jserv-servlet
handler (see our Apache-mod_jserv configuration
section).
Tomcat sends data back to the browser using the Transfer-Encoding:
Chunked method. This causes problems with Internet Explorer when
using SSL. The solution is to make sure the first line of the
returned file isn't blank.
The protocol used by mod_jserv can't identify whether a page was
requested via HTTP or HTTPS. Yes, Apache/JServ did it, but that
was a hack (just checked for requests on port 443). The solution
is either to check for port 443 yourself, or to upgrade to mod_jk and
the ajpv13 protocol. Another symptom of this is finding requests
redirected to http://yourserver.com:443
rather than https://yourserver.com/.
Tomcat doesn't support JSSI. Until someone writes an Interceptor to
handle them, the easiest way is to convert your .jhtml files to .jsp
files. Just replace:
<servlet name=myServlet>
<param name=aParam value=aValue>
</servlet>
with
<jsp:include page="/servlet/myServlet"
flush="true" >
<jsp:param name="aParam"
value="aValue" />
</jsp:include>
Tomcat implements the servlet specification v2.2, whereas JServ
implemented version 2.1. In the newer version, there are tighter
restrictions on the mapping from URL (what the user requests) to the
filename (what they get). Specifically, it insists that:
request URI = context path + servlet path + path info
This means that the arbitrary mappings that mod_rewrite is capable of
simply won't work without breaking the Servlet specification. One
solutions is to use the [R] flag on the RewriteRule directive to
"externally redirect" the request.
If you have a "<Location />" directive in your
httpd.conf file, this will take precedence over any ApJServMount
directives. The following example won't forward "/servlet"
requests to Tomcat.
ApJServMount /servlet /ROOT
<Location />
Options Indexes Multiviews
</Location>
A workaround is to use <Directory> instead of <Location>
If your UNIX-style box has an "rc.d"-style boot directory
(Solaris, RedHat, etc.), then the simplest way is to create a file in the
appropriate boot directory which looks something like this:
#!/bin/sh
CLASSPATH=/your/classpath/here
export CLASSPATH
su - nobody -c "/tomcat/bin/tomcat.sh $@"
You can then invoke this as /etc/rc.d/init.d/tomcat (start | stop) from
your boot sequence in the same way that you start Apache (for instance).
As of this writing (Sept. 30, 2000) mod_jk has to be built from the
Tomcat source distibution.
mod_jk reuses the same port when talking to Tomcat, unlike mod_jserv.
You'll need to restart Apache whenever you restart Tomcat.
This document was created by
Gal Shachor. It was split
off into a separate document and revised by Rob Slifka and Mike Bremford.
Contributors, listed in alphabetical order:
- Jonathan Bnayahu
- Mike Bremford
- Alex Chaffee
- Fiona Czuczman
- Costin Manolache
- Chris Pepper
- Rob Slifka
- ...the countless many on the tomcat-dev and tomcat-user lists!
Copyright ©1999-2000 The Apache Software Foundation
Legal Stuff They Make Us Say
Contact Information