|
|
Apache HowTo |
|
 Introduction |
This document explains how to connect Tomcat to the popular open source web server, Apache. There is actually two version of Apache, 1.3 and 2.0 and both can be used with mod_jk, the Tomcat redirector module.
It is recommanded that you also read the Workers HowTo document to learn how to setup the working entities between your WebServer and Tomcat Engines.
This document was originally part of Tomcat: A Minimalistic User's Guide written by Gal Shachor, but has been split off for organizational reasons.
|
Document Conventions and Assumptions |
${tomcat_home} is the root directory of tomcat. Your Tomcat installation should have the following subdirectories:
- ${tomcat_home}\conf - Where you can place various configuration files
- ${tomcat_home}\webapps - Containing example applications
- ${tomcat_home}\bin - Where you place web server plugins
In all the examples in this document ${tomcat_home} will be /var/tomcat3 . A worker is defined to be a tomcat process that accepts work from the Apache server.
|
Supported Configuration |
The mod_jk module was developed and tested on:
- Linux, FreeBSD, AIX, HP-UX, MacOS X, and should works on major Unixes platforms supporting Apache 1.3 and/or 2.0
- WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98
- Cygwin (until you have an apache server and autoconf/automake support tools)
- Netware
- iSeries V5R1 and V5R2 with Apache 2.0.39. Be sure to have the latest Apache PTF installed.
- Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x and Tomcat 5
The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. There is also an option to use Tomcat in process, more about the in-process mode can be found in the in process howto.
|
Who support ajp protocols ? |
The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x.
The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead ajp13 which is the only ajp protocol known by Tomcat 4.0.x, 4.1.x and 5.
Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol.
Others servlet engines such as jetty have support for ajp13 protocol
|
How does it work ? |
In a nutshell a web server is waiting for client HTTP requests. When these requests arrive the server does whatever is needed to serve the requests by providing the necessary content.
Adding a servlet container may somewhat change this behavior. Now the web server needs also to perform the following:
- Load the servlet container adapter library and initialize it (prior to serving requests).
- When a request arrives, it needs to check and see if a certain request belongs to a servlet, if so it needs to let the adapter take the request and handle it.
The adapter on the other hand needs to know what requests it is going to serve, usually based on some pattern in the request URL, and to where to direct these requests.
Things are even more complex when the user wants to set a configuration that uses virtual hosts, or when they want multiple developers to work on the same web server but on different servlet container JVMs. We will cover these two cases in the advanced sections.
|
Obtaining mod_jk |
mod_jk can be obtained in two formats - binary and source. Depending on the platform you are running your web server on, a binary version of mod_jk may be available.
It is recommended to use the binary version if one is available. If the binary is not available, follow the instructions for building mod_jk from source. The mod_jk source can be downloaded from a mirror here
The binaries for mod_jk are now available, for several platforms, in a separate area as the Tomcat Binary Release. The binaries are located in subdirectories by platform.
For some platforms, such as Windows, this is the typical way of obtaining mod_jk since most Windows systems do not have C compilers.
For others, the binary distribution of mod_jk offers simpler installation.
For example JK 1.2.5 can be downloaded from a mirror here and contains binary version for a variety of operating systems for both Apache 1.3 and Apache 2.
|
Installation |
mod_jk requires two entities:
- mod_jk.xxx - The Apache module, depending on your operating system, it will be mod_jk.so, mod_jk.dll, mod_jk,nlm or or QZTCJK.SRVPGM (see the build section).
- workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers.properties can be found under the conf directory.
Also as with other Apache modules, mod_jk should be first installed on the modules directory of your Apache webserver, ie : /usr/lib/apache and you should update your httpd.conf file.
|
Disabling old mod_jserv |
If you've previously configured Apache to use mod_jserv , remove any ApJServMount directives from your httpd.conf.
If you're including tomcat-apache.conf or tomcat.conf , you'll want to remove them as well - they are specific to mod_jserv .
The mod_jserv configuration directives are not compatible with mod_jk !
|
Using Tomcat auto-configure |
The simplest way to configure Apache to use mod_jk is to turn on the Apache auto-configure setting in Tomcat and put the following include directive at the end of your Apache httpd.conf file (make sure you replace TOMCAT_HOME with the correct path for your Tomcat installation:
|
To be added at the end of your httpd.conf
|
This will tell Apache to use directives in the mod_jk.conf-auto file in the Apache configuration. This file is created by enabling the Apache auto-configuration as described in the Tomcat documentation.
|
Custom mod_jk configuration |
You should use custom configuration when :
- You couldn't use mod_jk.conf-auto since Tomcat engine isn't on the same machine that your Apache WebServer, ie when you have an Apache in front of a Tomcat Farm.
- Another case for custom configuration is when your Apache is in front of many differents Tomcat engines, each one having it's own configuration, a general case in ISP hosting
- Also all Apache webmaster will retain custom configuration to be able to tune the settings to their real needs.
|
Simple configuration example |
Here is a simple configuration:
|
# Load mod_jk module
# Declare the module for <IfModule directive>
# Where to find workers.properties
# Where to put jk logs
# Set the jk log level [debug/error/info]
# Select the log format
# JkOptions indicate to send SSL KEY SIZE,
# JkRequestLogFormat set the request format
# Send servlet for context /examples to worker named worker1
# Send JSPs for context /examples to worker named worker1
|
|
mod_jk Directives |
We'll discuss here the mod_jk directives and details behind them
|
Define workers |
JkWorkersFile specify the location where mod_jk will find the workers definitions.
|
|
Logging |
JkLogFile specify the location where mod_jk is going to place its log file.
|
JkLogLevel set the log level between :
- info log will contains standard mod_jk activity (default).
- error log will contains also error reports.
- debug log will contains all informations on mod_jk activity
|
info should be your default selection for normal operations.
JkLogStampFormat will configure the date/time format found on mod_jk logfile. Using the strftime() format string it's set by default to "[%a %b %d %H:%M:%S %Y]"
|
JkRequestLogFormat will configure the format of mod_jk individual request logging. Request logging is configured and enabled on a per virtual host basis. To enable request logging for a virtual host just add a JkRequestLogFormat config. The syntax of the format string is similiar to the Apache LogFormat command, here is a list of the available request log format options:
| Options | Description |
| %b | Bytes sent, excluding HTTP headers (CLF format) |
| %B | Bytes sent, excluding HTTP headers |
| %H | The request protocol |
| %m | The request method |
| %p | The canonical Port of the server serving the request |
| %q | The query string (prepended with a ? if a query string exists, otherwise an empty string) |
| %r | First line of request |
| %s | Request HTTP status code |
| %T | Request duration, elapsed time to handle request in seconds '.' micro seconds |
| %U | The URL path requested, not including any query string. |
| %v | The canonical ServerName of the server serving the request |
| %V | The server name according to the UseCanonicalName setting |
| %w | Tomcat worker name |
|
|
Forwarding |
The directive JkOptions allow you to set many forwarding options which will enable (+)
or disable (-) following option.
JkOptions ForwardKeySize , you ask mod_jk, when using ajp13, to forward also the SSL Key Size as required by Servlet API 2.3. This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default).
|
JkOptions ForwardURICompat , you told mod_jk to send the URI to Tomcat normally, which is less spec compliant but mod_rewrite compatible, use it for compatibility with Tomcat 3.2.x engines (on by default).
|
JkOptions ForwardURICompatUnparsed , the forwarded URI is unparsed so it needs to let the adapter take the request and handle it.
The adapter on the other hand needs to know what requests it is going to serve, usually based on some pattern in the request URL, and to where to direct these requests.
Things are even more complex when the user wants to set a configuration that uses virtual hosts, or when they want multiple developers to work on the same web server but on different servlet container JVMs. We will cover these two cases in the advanced sections.
|
Obtaining mod_jk |
mod_jk can be obtained in two formats - binary and source. Depending on the platform you are running your web server on, a binary version of mod_jk may be available.
It is recommended to use the binary version if one is available. If the binary is not available, follow the instructions for building mod_jk from source. The mod_jk source can be downloaded from a mirror here
The binaries for mod_jk are now available, for several platforms, in a separate area as the Tomcat Binary Release. The binaries are located in subdirectories by platform.
For some platforms, such as Windows, this is the typical way of obtaining mod_jk since most Windows systems do not have C compilers.
For others, the binary distribution of mod_jk offers simpler installation.
For example JK 1.2.5 can be downloaded from a mirror here and contains binary version for a variety of operating systems for both Apache 1.3 and Apache 2.
|
Installation |
mod_jk requires two entities:
- mod_jk.xxx - The Apache module, depending on your operating system, it will be mod_jk.so, mod_jk.dll, mod_jk,nlm or or QZTCJK.SRVPGM (see the build section).
- workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers.properties can be found under the conf directory.
Also as with other Apache modules, mod_jk should be first installed on the modules directory of your Apache webserver, ie : /usr/lib/apache and you should update your httpd.conf file.
|
Disabling old mod_jserv |
If you've previously configured Apache to use mod_jserv , remove any ApJServMount directives from your httpd.conf.
If you're including tomcat-apache.conf or tomcat.conf , you'll want to remove them as well - they are specific to mod_jserv .
The mod_jserv configuration directives are not compatible with mod_jk !
|
Using Tomcat auto-configure |
The simplest way to configure Apache to use mod_jk is to turn on the Apache auto-configure setting in Tomcat and put the following include directive at the end of your Apache httpd.conf file (make sure you replace TOMCAT_HOME with the correct path for your Tomcat installation:
|
To be added at the end of your httpd.conf
|
This will tell Apache to use directives in the mod_jk.conf-auto file in the Apache configuration. This file is created by enabling the Apache auto-configuration as described in the Tomcat documentation.
|
Custom mod_jk configuration |
You should use custom configuration when :
- You couldn't use mod_jk.conf-auto since Tomcat engine isn't on the same machine that your Apache WebServer, ie when you have an Apache in front of a Tomcat Farm.
- Another case for custom configuration is when your Apache is in front of many differents Tomcat engines, each one having it's own configuration, a general case in ISP hosting
- Also all Apache webmaster will retain custom configuration to be able to tune the settings to their real needs.
|
Simple configuration example |
Here is a simple configuration:
|
# Load mod_jk module
# Declare the module for <IfModule directive>
# Where to find workers.properties
# Where to put jk logs
# Set the jk log level [debug/error/info]
# Select the log format
# JkOptions indicate to send SSL KEY SIZE,
# JkRequestLogFormat set the request format
# Send servlet for context /examples to worker named worker1
# Send JSPs for context /examples to worker named worker1
|
|
mod_jk Directives |
We'll discuss here the mod_jk directives and details behind them
|
Define workers |
JkWorkersFile specify the location where mod_jk will find the workers definitions.
|
|
Logging |
JkLogFile specify the location where mod_jk is going to place its log file.
|
JkLogLevel set the log level between :
- info log will contains standard mod_jk activity (default).
- error log will contains also error reports.
- debug log will contains all informations on mod_jk activity
|
info should be your default selection for normal operations.
JkLogStampFormat will configure the date/time format found on mod_jk logfile. Using the strftime() format string it's set by default to "[%a %b %d %H:%M:%S %Y]"
|
JkRequestLogFormat will configure the format of mod_jk individual request logging. Request logging is configured and enabled on a per virtual host basis. To enable request logging for a virtual host just add a JkRequestLogFormat config. The syntax of the format string is similiar to the Apache LogFormat command, here is a list of the available request log format options:
| Options | Description |
| %b | Bytes sent, excluding HTTP headers (CLF format) |
| %B | Bytes sent, excluding HTTP headers |
| %H | The request protocol |
| %m | The request method |
| %p | The canonical Port of the server serving the request |
| %q | The query string (prepended with a ? if a query string exists, otherwise an empty string) |
| %r | First line of request |
| %s | Request HTTP status code |
| %T | Request duration, elapsed time to handle request in seconds '.' micro seconds |
| %U | The URL path requested, not including any query string. |
| %v | The canonical ServerName of the server serving the request |
| %V | The server name according to the UseCanonicalName setting |
| %w | Tomcat worker name |
|
|
Forwarding |
The directive JkOptions allow you to set many forwarding options which will enable (+)
or disable (-) following option.
JkOptions ForwardKeySize , you ask mod_jk, when using ajp13, to forward also the SSL Key Size as required by Servlet API 2.3. This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default).
|
JkOptions ForwardURICompat , you told mod_jk to send the URI to Tomcat normally, which is less spec compliant but mod_rewrite compatible, use it for compatibility with Tomcat 3.2.x engines (on by default).
|
JkOptions ForwardURICompatUnparsed , the forwarded URI is unparsed so it needs to let the adapter take the request and handle it.
The adapter on the other hand needs to know what requests it is going to serve, usually based on some pattern in the request URL, and to where to direct these requests.
Things are even more complex when the user wants to set a configuration that uses virtual hosts, or when they want multiple developers to work on the same web server but on different servlet container JVMs. We will cover these two cases in the advanced sections.
|
Obtaining mod_jk |
mod_jk can be obtained in two formats - binary and source. Depending on the platform you are running your web server on, a binary version of mod_jk may be available.
It is recommended to use the binary version if one is available. If the binary is not available, follow the instructions for building mod_jk from source. The mod_jk source can be downloaded from a mirror here
The binaries for mod_jk are now available, for several platforms, in a separate area as the Tomcat Binary Release. The binaries are located in subdirectories by platform.
For some platforms, such as Windows, this is the typical way of obtaining mod_jk since most Windows systems do not have C compilers.
For others, the binary distribution of mod_jk offers simpler installation.
For example JK 1.2.5 can be downloaded from a mirror here and contains binary version for a variety of operating systems for both Apache 1.3 and Apache 2.
|
Installation |
mod_jk requires two entities:
- mod_jk.xxx - The Apache module, depending on your operating system, it will be mod_jk.so, mod_jk.dll, mod_jk,nlm or or QZTCJK.SRVPGM (see the build section).
- workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers.properties can be found under the conf directory.
Also as with other Apache modules, mod_jk should be first installed on the modules directory of your Apache webserver, ie : /usr/lib/apache and you should update your httpd.conf file.
|
Disabling old mod_jserv |
If you've previously configured Apache to use mod_jserv , remove any ApJServMount directives from your httpd.conf.
If you're including tomcat-apache.conf or tomcat.conf , you'll want to remove them as well - they are specific to mod_jserv .
The mod_jserv configuration directives are not compatible with mod_jk !
|
Using Tomcat auto-configure |
The simplest way to configure Apache to use mod_jk is to turn on the Apache auto-configure setting in Tomcat and put the following include directive at the end of your Apache httpd.conf file (make sure you replace TOMCAT_HOME with the correct path for your Tomcat installation:
|
To be added at the end of your httpd.conf
|
This will tell Apache to use directives in the mod_jk.conf-auto file in the Apache configuration. This file is created by enabling the Apache auto-configuration as described in the Tomcat documentation.
|
Custom mod_jk configuration |
You should use custom configuration when :
- You couldn't use mod_jk.conf-auto since Tomcat engine isn't on the same machine that your Apache WebServer, ie when you have an Apache in front of a Tomcat Farm.
- Another case for custom configuration is when your Apache is in front of many differents Tomcat engines, each one having it's own configuration, a general case in ISP hosting
- Also all Apache webmaster will retain custom configuration to be able to tune the settings to their real needs.
|
Simple configuration example |
Here is a simple configuration:
|
# Load mod_jk module
# Declare the module for <IfModule directive>
# Where to find workers.properties
# Where to put jk logs
# Set the jk log level [debug/error/info]
# Select the log format
# JkOptions indicate to send SSL KEY SIZE,
# JkRequestLogFormat set the request format
# Send servlet for context /examples to worker named worker1
# Send JSPs for context /examples to worker named worker1
|
|
mod_jk Directives |
We'll discuss here the mod_jk directives and details behind them
|
Define workers |
JkWorkersFile specify the location where mod_jk will find the workers definitions.
|
|
Logging |
JkLogFile specify the location where mod_jk is going to place its log file.
|
JkLogLevel set the log level between :
- info log will contains standard mod_jk activity (default).
- error log will contains also error reports.
- debug log will contains all informations on mod_jk activity
|
info should be your default selection for normal operations.
JkLogStampFormat will configure the date/time format found on mod_jk logfile. Using the strftime() format string it's set by default to "[%a %b %d %H:%M:%S %Y]"
|
JkRequestLogFormat will configure the format of mod_jk individual request logging. Request logging is configured and enabled on a per virtual host basis. To enable request logging for a virtual host just add a JkRequestLogFormat config. The syntax of the format string is similiar to the Apache LogFormat command, here is a list of the available request log format options:
| Options | Description |
| %b | Bytes sent, excluding HTTP headers (CLF format) |
| %B | Bytes sent, excluding HTTP headers |
| %H | The request protocol |
| %m | The request method |
| %p | The canonical Port of the server serving the request |
| %q | The query string (prepended with a ? if a query string exists, otherwise an empty string) |
| %r | First line of request |
| %s | Request HTTP status code |
| %T | Request duration, elapsed time to handle request in seconds '.' micro seconds |
| %U | The URL path requested, not including any query string. |
| %v | The canonical ServerName of the server serving the request |
| %V | The server name according to the UseCanonicalName setting |
| %w | Tomcat worker name |
|
|
Forwarding |
The directive JkOptions allow you to set many forwarding options which will enable (+)
or disable (-) following option.
JkOptions ForwardKeySize , you ask mod_jk, when using ajp13, to forward also the SSL Key Size as required by Servlet API 2.3. This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default).
|
JkOptions ForwardURICompat , you told mod_jk to send the URI to Tomcat normally, which is less spec compliant but mod_rewrite compatible, use it f