This document describes how to integrate the
Ozibug application running in the Jakarta Tomcat
Web Container (Tomcat) with the Microsoft Internet
Information Service (IIS) application.
Further documentation on this can
be found in the TOMCAT_HOME/doc
directory.
The examples use the ajp12 connector and
Jakarta Tomcat release 3.2.1.
IIS can be used to wrap the requests
and responses to and from the Tomcat Web Container.
It can pass through the requests for the Ozibug
servlets but handle the static files and images
itself freeing Tomcat of additional work.
This is useful for several reasons.
Logging
IIS can be configured to produce standard and custom
logging reports. These can then be used to analyze
and perhaps optimize the traffic to and from your
web applications.
Speed
Web applications typically consist of static
files containing images, scripts, and documents
and some dynamically generated content.
These static files can then be served by a
faster Web Server (such as IIS) which is
specifically designed for this purpose rather
than the Web Container, which is tuned for
serving the dynamically generated content.
Security
With the Web Server receiving the HTTP requests
from the internet, this becomes the first line
of defence against attacks. As such there are
usually many security features that the Web Server
provides which will stop rogue attacks against
the underlying infrastructure (Web Container.)
Integration
By using a Web Server as a common front end
it is easy to integrate multiple applications
and web sites and redirectors behind it. This
usually allows great flexibility in adding,
changing and removing the content and services
behind it.
This section gives a quick overview of the
operations you must carry out.
Tomcat
Configure the workers.properties
and uriworkermap.properties file.
Create the registry file
iis_redirect.reg and insert the
contents into the Windows registry.
Reconfigure Tomcat by editing the
server.xml file.
IIS
Download the isapi_redirect.dll file.
Create the OzibugServlet directory,
copy the isapi_redirect.dll file into
it and add to IIS as a virtual directory.
Add the OZIBUG_HOME directory
to IIS as a virtual directory.
Restrict permissions for the
OZIBUG_HOME\WEB-INF sub-directory.
Add the filename index.html to
the default file list.
Add the isapi_redirect.dll as an
ISS ISAPI filter.
Start/Stop
You will need to stop and restart both
Tomcat and IIS.
Test
Test your installation thoroughly, if all
is OK then continue with the following steps.
Raise the loglevel of the Tomcat plugin by
updating the value in the file
iis_redirect.reg and re-applying this
to the registry. This will reduce the
amount of unwanted logging.
Remove (or comment out) the Tomcat Connector
on port 8080 from the server.xml file.
This will enhance the security of the installation.
This is the location of Tomcat.
The configuration, logging, work and webapps
directories are all underneath this directory.
This location is dependent on where you
installed Tomcat.
This is the location of the Ozibug servlet.
This directory is created when Ozibug is
installed into Tomcat. This is dependant
on where you installed Tomcat and how
you have installed Ozibug into Tomcat.
A working example of this file is contained in
Appendix B
This file should only contain the following
definitions.
/ozibug/Controller=ajp12
/ozibug/Stylesheet=ajp12
TOMCAT_HOME\conf\iis_redirect.reg
This file must be created, a working example
of this file is contained in
Appendix C.
This file contains entries that the redirector
plugin will use to find the Tomcat installation.
These entries are inserted into the registry.
You can do this by highlighting the finished
file in your Windows Explorer and double
clicking on it. This will invoke the regedit
program which will insert the entries.
extension_uri
This key is a link to the tomcat redirector plugin.
log_file
This key defines the logfile
that the plugin will use. The logfile should
be defined in the TOMCAT_HOME\logs
directory.
log_level
This key defines the log level
that the plugin will use.
The level can be one of the following values
"debug", "info", "error" or "emerg". Initially
this should be set to debug, after the installation
has been tested it should be set to error.
worker_file
This key should contain the filename of the
workers.properties file defined in
Section 4.1.
worker_mount_file
This key should contain the filename of the
uriworkermap.properties file defined in
Section 4.2.
NOTE: that the entries in this file
are wrapped in double quotes and the filenames
contain double backslashes as the file separator
character (except the extension_uri value.)
TOMCAT_HOME\conf\server.xml
A working example of this file is contained in
Appendix D.
This file contains the Tomcat configuration data in XML
format. This must be edited to change the port numbers
that Tomcat uses (as by default these will conflict with
the Web Server ports.)
The connector entry that defines the HTTP entry for port
80 should be changed to port 8080. This entry will look
like this after editing.
The following steps need to be carried out to
configure the IIS application.
Tomcat Redirector Directory
Create the directory C:\OzibugServlet
and copy in the file isapi_redirect.dll.
This file can be downloaded from the
jakarta-tomcat
website. It is included in the
win32/i386 directory underneath the
binaries directory.
The C:\OzibugServlet
directory is simply used to hold the
redirector plugin and also give meaning to
the name that the IIS Web Server logs whenever
the Ozibug application is accessed.
Using the IIS management console you must add the
C:\OzibugServlet directory as a virtual
directory of the web site you have chosen.
Once added make sure that only the execute permission
is given to this directory.
NOTE: By default the MS Explorer file manager
hides files that have the ".dll" extension. This
setting can be changed on Windows NT by selecting
the "view" and "options" from the top menu bar and
unselecting the checkbox. On Windows 2K it can be
changed by selecting "tools" and "folder options"
from the top menu.
OZIBUG_HOME Directory
The OZIBUG_HOME directory which is defined in
section 3.3,
must be added as a virtual directory
to IIS using the IIS management console.
Once added you must make sure that the WEB-INF
directory dous not have read, write or execute permissions.
This directory is located directly underneath the
main Ozibug directory.
You can remove permissions by selecting the directory,
clicking the right mouse button to retrieve the context
menu and selecting properties. A dialog box is displayed
where you can remove permissions. Do this and then select
the Apply button.
Default filename
Using the IIS management console you must add the filename
index.html to the default document list.
This list of filenames is tried by the Web Server when
a request is received which does not have a filename
associated with it.
This can be done by selecting the configured web site,
clicking with the right mouse button to retrieve the context
menu and then selecting the properties menu item. The document
list is a tabbed pane on the dialog which is displayed.
Mime types
By default IIS doesn't configure all the mime types
that are usually contained in an extensive web application.
These must be added to IIS so that the correct content
type is sent to the browser.
Using the IIS Management Console select the
web site that you have been using. Then
using the right mouse button select the
context menu and select the properties menu option.
This displays the configuration dialog box for the
web site. Select the HTTP Headers tab and at the
bottom of the dialog box is the MIME Map. Push
the File Types button which will display the
File Types editor.
By selecting the New Type button you can add
a new mime type. Enter the filename extension
into the associated extension field and the
correct mime type into the Content Type field.
Selecting OK will then add this type to IIS.
The following mime types should be added.
Associated extension
Content Type (Mime)
css
text/css
js
text/javascript
xml
text/xml
Tomcat Redirector Filter
Using the IIS management console you must now add the file
C:\OzibugServlet\isapi_redirect.dll as an ISAPI filter.
The name should reflect its use so use Ozibug.
Restart the IIS service - this should be done from the services
tool (not the IIS management console.) Once restarted you can
see the green arrow against the Ozibug ISAPI filter
indicating that it is active.
# workers.properties
#
# This file provides jk derived plugins with with the needed
# information to connect to the different tomcat workers.
#
# As a general note, the characters $( and ) are used internally
# to define macros. Do not use them in your own configuration!!!
#
# Whenever you see a set of lines such as:
# x=value
# y=$(x)\something
#
# the final value for y will be value\something
#
# Normaly all you will need to modify is the first properties, i.e.
# workers.tomcat_home, workers.java_home and ps. Most of the
# configuration is derived from these.
#
# When you are done updating workers.tomcat_home, workers.java_home
# and ps you should have 3 workers configured:
#
# - An ajp12 worker that connects to localhost:8007
# - An ajp13 worker that connects to localhost:8009
# - A jni inprocess worker.
# - A load balancer worker
#
# However by default the plugins will only use the ajp12 worker.
# To have the plugins use other workers you should modify the
# worker.list property.
#
# workers.tomcat_home should point to the location where you
# installed tomcat. This is where you have your conf, webapps and lib
# directories.
#
workers.tomcat_home=C:\jakarta-tomcat
#
# workers.java_home should point to your Java installation. Normally
# you should have a bin and lib directories beneath it.
#
workers.java_home=C:\jdk1.3.1_04
#
# You should configure your environment slash... ps=\ on NT and / on UNIX
# and maybe something different elsewhere.
#
ps=\
# ps=/
#
#------ ADVANCED MODE ------------------------------------------------
#---------------------------------------------------------------------
#
#
#------ DEFAULT worket list ------------------------------------------
#---------------------------------------------------------------------
#
#
# The workers that your plugins should create and work with
#
worker.list=ajp12
#
#------ DEFAULT ajp12 WORKER DEFINITION ------------------------------
#---------------------------------------------------------------------
#
#
# Defining a worker named ajp12 and of type ajp12
# Note that the name and the type do not have to match.
#
worker.ajp12.port=8007
worker.ajp12.host=localhost
worker.ajp12.type=ajp12
#
# Specifies the load balance factor when used with
# a load balancing worker.
# Note:
# ----> lbfactor must be > 0
# ----> Low lbfactor means less work done by the worker.
worker.ajp12.lbfactor=1
#
#------ DEFAULT ajp13 WORKER DEFINITION ------------------------------
#---------------------------------------------------------------------
#
#
# Defining a worker named ajp13 and of type ajp13
# Note that the name and the type do not have to match.
#
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
#
# Specifies the load balance factor when used with
# a load balancing worker.
# Note:
# ----> lbfactor must be > 0
# ----> Low lbfactor means less work done by the worker.
worker.ajp13.lbfactor=1
#
# Specify the size of the open connection cache.
#worker.ajp13.cachesize
#
#------ DEFAULT LOAD BALANCER WORKER DEFINITION ----------------------
#---------------------------------------------------------------------
#
#
# The loadbalancer (type lb) workers perform wighted round-robin
# load balancing with sticky sessions.
# Note:
# ----> If a worker dies, the load balancer will check its state
# once in a while. Until then all work is redirected to peer
# workers.
worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=ajp12, ajp13
#
#------ DEFAULT JNI WORKER DEFINITION---------------------------------
#---------------------------------------------------------------------
#
#
# Defining a worker named inprocess and of type jni
# Note that the name and the type do not have to match.
#
worker.inprocess.type=jni
#
#------ CLASSPATH DEFINITION -----------------------------------------
#---------------------------------------------------------------------
#
#
# Additional class path components.
#
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)classes
#
# The XML parser provided with Tomcat
#
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)jaxp.jar
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)parser.jar
#
# Tomcat's implementation
#
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)jasper.jar
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)servlet.jar
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)webserver.jar
#
# Javac as available from Java2SE
#
worker.inprocess.class_path=$(workers.java_home)$(ps)lib$(ps)tools.jar
#
# Setting the command line for tomcat
# Note: The cmd_line string may not contain spaces.
#
worker.inprocess.cmd_line=-config
worker.inprocess.cmd_line=$(workers.tomcat_home)/conf/jni_server.xml
worker.inprocess.cmd_line=-home
worker.inprocess.cmd_line=$(workers.tomcat_home)
#
# The JVM that we are about to use
#
# This is for Java2
#
worker.inprocess.jvm_lib=$(workers.java_home)$(ps)jre$(ps)bin$(ps)classic$(ps)jvm.dll
#
# And this is for jdk1.1.X
#
#worker.inprocess.jvm_lib=$(workers.java_home)$(ps)bin$(ps)javai.dll
#
#
# Setting the place for the stdout and stderr of tomcat
#
worker.inprocess.stdout=$(workers.tomcat_home)$(ps)inprocess.stdout
worker.inprocess.stderr=$(workers.tomcat_home)$(ps)inprocess.stderr
#
# Setting the tomcat.home Java property
#
worker.inprocess.sysprops=tomcat.home=$(workers.tomcat_home)
#
# Java system properties
#
# worker.inprocess.sysprops=java.compiler=NONE
# worker.inprocess.sysprops=myprop=mypropvalue
#
# Additional path components.
#
# worker.inprocess.ld_path=d:$(ps)SQLLIB$(ps)bin
#
