How To Integrate IIS6 and Apache Tomcat

thumbsshameΔιακομιστές

17 Νοε 2013 (πριν από 3 χρόνια και 6 μήνες)

125 εμφανίσεις

How To Integrate IIS6 and Apache Tomcat

By Glenn Barnas / InnoTech Consulting Group

www.innotechcg.com


This is a step by step guide to installing Apache Tomcat 6.x
on systems running IIS 6.0. The process
should work on other combinations of IIS and Tomcat with minimal adjustments.

System Configuration:

For this installation, I used the latest versions of software available during May, 2007.



Windows Server 2003 Standa
rd Edition (no change for Enterprise) w/ SP
-
2



Internet Information Services (IIS) 6.0



Sun Java Runtime


JRE 6.0 Update 1



Apache Jakarta Tomcat version 6.0.13



The isapi_redirect.dll version 1.2.22



Install the Java Runtime Environment

Launch the JRE inst
aller. When prompted, choose a custom installation. I disable the browser
integration, media support, and change the install path as shown. Click Next to start the install.



Fig. 1


Java JRE Setup



Fig. 2


JRE Installation Complete

I prefer to run an automated install for this


the command line I used is shown below. You will need
to reflect the correct JRE.exe file name, and possibly change t
he location of the log file.

jre
-
6u1
-
windows
-
i586
-
p.exe /s ADDLOCAL=jrecore INSTALLDIR=%ProgramFiles%
\
Java
\
Jre IEXPLORER=0
MOZILLA=0 JAVAUPDATE=0 REBOOT=Suppress WEBSTARTICON=0 /L %SYSTEMDRIVE%
\
Temp
\
JRE6setup.log

If you use the automated install command, J
ava Automatic Updates are disabled. This is our
preferred setting on servers, so we can control the “what and when” updating process. If you
manually installed Java, you can disable the automatic updates in the Java control panel.

Configuration of Java an
d Tomcat

Both Java and Tomcat need environment variables defined so applications can locate the folders that
they are installed to. Open the System Properties dialog box and select the Advanced tab. (right
-
click
“My Computer” and choose Properties) Click t
he “Environment Variables” button at the bottom of
the dialog box.




Fig. 3


System Properties Dialog Box


Fig. 4


Environment Variables Dia
log Box

Click “New” on the System (lower) section of the Environment Variables dialog box. The
applications will not work with User variables! When prompted, add a new system variable called
JAVA_HOME


Set the value to the location where Java was installe
d. We consider Java a system
application, so it is installed to C:
\
Program Files.


Fig. 5



Setting the Java Environment Variable

While we are here, define the CATALINA_HOME system variable that Tomcat

requires. Specify
the path where you have decided to install Tomcat. We consider this an “external” application, so it
is installed to the application drive


E:
\
Apps
\
Tomcat in this case.


Fig. 6


Set
ting the Tomcat Environment Variable

Installing Tomcat

We are ready to begin the Tomcat installation at this point. Since Tomcat is designed to work with
several different web servers, it is not delivered with any components or configuration files for
spec
ific web servers. Since this is the case, and IIS requires specific components and configuration
files, I prefer to put them in place before the installation of Tomcat.

Preparation

Having decided to install Tomcat to E:
\
Apps
\
Tomcat, start by creating some
of the folders that
Tomcat will use. We need to place two “.properties” files into the /conf folder, and put the
“isapi_redirect.dll” file into the /bin/win32/i386 folder. The location of the redirector DLL is up to
you, but this is the standard location u
sed by Tomcat in the past. In the steps below, “<TOMCAT>”
refers to the folder where Tomcat is installed, as specified in the “CATALINA_HOME”
environment variable you defined earlier.



Create the <TOMCAT>
\
conf folder



Create the <TOMCAT>
\
bin
\
win32
\
i386 folder



Copy the isapi_redirect.dll file to <TOMCAT>
\
bin
\
win32
\
i386



Create a “workers.properties” file in the <TOMCAT>
\
conf folder. Copy the following lines
to that file to create a default configuration for testing.

# 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



Create a “uriworkermap.properties” file in the <TOMCAT>
\
conf folder. Copy the following
lines to that file

to create a default configuration for testing. This assumes that the root of the
Tomcat examples folder is called “examples”.


This is the default installation method for this
version.

/examples/*=worker1

/examples/*.jsp=worker1

/examples/servlet/*=worker
1



Copy the following lines to a file called isapi.reg, and merge this registry file into your
server’s system registry.
Be sure to edit the 3 path definitions to reflect your
configuration before merging the registry file!

Windows Registry Editor Version 5.00


[HKEY_LOCAL_MACHINE
\
SOFTWARE
\
Apache Software Foundation
\
Jakarta Isapi Redirector]


[HKEY_LOCAL_MACHINE
\
SOFTWARE
\
Apache Software Foundation
\
Jakarta Isapi Redirector
\
1.0]

"extension_uri"="/jakarta/isapi_redirect.dll"

"l
og_file"="E:
\
\
Apps
\
\
Tomcat
\
\
logs
\
\
isapi.log"

"log_level"="debug"

"worker_file"="E:
\
\
Apps
\
\
Tomcat
\
\
conf
\
\
workers.properties"

"worker_mount_file"="E:
\
\
Apps
\
\
Tomcat
\
\
conf
\
\
uriworkermap.properties"

You will want to edit the “.properties” files after the basic
configuration is working to reflect your
production environment. These are simply sample files to illustrate the relationship between workers
and URIs. These files will be reviewed in some detail at the end of this document.

Launch the Tomcat Installer

Run

the
apache
-
tomcat
-
6.0.13.exe

command to start the installation process. Click “next” on the
splash screen, and “I Agree” on the license agreement screen.

When prompted to choose components, select “Full” for the first Tomcat installation so you have
acces
s to all of the example .JSP and Servelet files. For production installations, choose “Custom”,
select Tomcat and all its sub
-
items, and de
-
select everything else.



Fig. 7
-

Tomcat Setup Dialog for Cus
tom Install

After choosing the components appropriate for your installation, you can select the install location.
Browse to the folder you specified in CATALINA_HOME. As I mentioned earlier, we prefer to not
install application software on the drive contai
ning the O/S.



Fig. 8


Define the installation folder



Define the HTTP/1.1 Connector Port and Admin ID/Password on the next screen. The Connector
Port is the TCP/IP port that the Tomcat service will
be listening on. If no other web server is
utilizing this port, accept the default of 8080, otherwise choose an available port.

Define an appropriate user name and password for web
-
based Tomcat administration. Be sure to
follow your company’s guidelines fo
r secure passwords on production servers.


Fig. 9


Configuring the Tomcat Connector port and Admin password

The installer will locate your JRE path


change it only if necessary.


Fig. 10


Configuring the JVM/JRE path

Click Install to complete the Tomcat installation process. When the installation completes, you will
be presented with the opportunity to start the Tomcat servic
e and view the Readme file. It is OK to
start the service at this time (since we already put the needed configuration files in place), and it is a
good idea to review the Readme file.


Fig. 11


Tomcat

Installation is complete

Verify that the installation has added a new service called “Apache Tomcat” (Tomcat6). Check that
it is running, and that it is set to start automatically.


Fig. 12


The Apache Tomcat service

Test the Tomcat Installation

On the system where you installed Tomcat, launch a web browser and connect to
http://localhost:8080
. You should see the Tomcat home page display.


Fig. 13

Default Tomcat web page on port 8080

You should take a few moments to test the JSP and Servlet examples to
verify that everything is
functioning properly.


Fig. 14


Testing the Tomcat installation

Integrating IIS and Tomca
t

Since we adhere to strict Best Practice standards for IIS installations, I want to explain our
configuration before continuing. We do not use the
inetpub

folder structure at all. We instead create
a
webfiles

folder on the application drive. In the
webfiles

folder, we create a subfolder for each web
instance, including the Default instance. Each of these instance subfolders has a
web

subfolder that
becomes the root of the web instance. This provides some physical isolation between multiple web
instan
ces on a single system.


It also permits folders to be created within a web application that are
not directly part of the web structure.

Preparation

Before beginning the IIS/Tomcat integration, I prepared the IIS web server to have a Default web
instance,
and an application instance that would employ Tomcat. You can see this configuration in
Figs. 15 and 16. I placed simple
default.htm

files in the root of each web instance that clearly
identified the web instance that was returning the page. The home page
message reported that the
Default or Primary Production instance had replied. These pages helped in troubleshooting during
the integration process.


Fig. 15


Web Site Configuration


Fig 16


Web Folder Structure

You do not have to fol
low this structure for the IIS/Tomcat integration to work. This information is
presented so that you can make sense of the remaining configuration settings and adapt them to your
environment. In many cases, you will need to point to web applications outsid
e of the default web
data structure!


Fig 17


Sample Home Page to Identify Web Instance

IIS Configuration


jakarta Virtual Directory

All of the following configurations will take place in the IIS Management conso
le.

Create a virtual directory called “jakarta”


the spelling and case is significant! The path should
reference the location of the isapi_redirect.dll file (<TOMCAT>/bin/win32/i386 by default). Check
the Execute box.




Fig. 18


Virtual Directory Alias


Fig. 19


Virtual Directory Path


Fig. 20


Virtual
Directory Access Permissions

IIS Configuration


Define Application Pool

It is recommended that each web instance run with its own application pool. If you are configuring
Tomcat to support an application web instance, create a separate application pool fo
r Tomcat and
change the web instance configuration to utilize it.




Fig. 21


New Application Pool


Fig. 22


Define applica
tion pool

IIS Configuration


Web Service Extension

In the IIS Manager, right
-
click on the Web Service Extensions object and select “New Web Service
Extension. Enter an extension name of “Tomcat”, enable the checkbox “Set extension status to
Allowed”, then

click “Add” and browse to the path where the isapi_redirect.dll is located. Select the
file and click OK. Verify that the Tomcat extension appears in the list with an “Allowed” status (Fig.
25).




Fig. 23


Add a web service exte
nsion


Fig. 24


Specify path to isapi_redirect.dll


Fig. 25


Web Service Extensions showing Tomcat extension and Allowed status

IIS Configuration


Define the Tomcat ISAPI Filter

The web instance needs to know that it should utilize the ISAPI redirection filter. This is done by
registering it in the application we
b site properties.

Open the properties panel of the web instance you are configuring to operate with Tomcat. Select the
ISAPI Filters tab and click the Add button. Set the filter name to “tomcat”, and browse to the
location of the isapi_redirect.dll file.
Click OK. The status and priority values will not display (or
show “* Unknown *” ) until the first time the redirector is loaded. The filter will not load until the
first time it is needed.




Fig. 26


Add ISAPI Filter


Fig. 27


Web Properties dialog
box

At this point, configuration is complete. Run
iisreset

to reinitialize the web server environment. Any
.JSP or servlets placed within the physical web structure will be intercepted by the isapi filter,
although the
uriworkermap.properties
file will nee
d to refer to the path where the .jsp or servlet files
have been placed. This relationship will become clear when you perform the next step, which
configures the Tomcat example files.

IIS Configuration


Tomcat Examples

This is the part of the configuratio
n that most often fails to function. This is likely due to not
recognizing the relationship between the workers file, uriworkermap file, and IIS itself.

Our example
workers.properties
file defines a single
worker thread


worker1


for testing purposes.
It defines the “ajp13” protocol, binds to localhost on port 8009. These values are appropriate for
most configurations that perform local redirection. You can define multiple worker threads to
support multipl
e instances or application paths. Simply add more names to the declaration line, and
duplicate the specification lines, editing them for each worker’s name.

The example
uriworkermap.properties

file maps requests for specific application paths to specific
w
orkers. This file is configured to map the Tomcat /examples folder path to a targeted worker called
“worker1”. Since we only defined one worker in the
workers.properties

file, the mapping file maps
everything to that worker.

If you tried to access http://
localhost/examples right now, you’d experience a 404 error. This is
because IIS is not aware of that path! Think about where the /examples path is… try
http://localhost:8080/examples. Of course, it works because the web server built into Tomcat
(listening
on port 8080) knows that the /examples URI is physically located at
E:
\
Apps
\
Tomcat
\
webapps
\
examples. IIS has no knowledge of this location (yet), so it returns the 404
error.

Let’s make IIS recognize this location by creating a virtual directory.

Create
a virtual directory called “examples”. The path should reference the location of the tomcat
examples folder (<TOMCAT>
\
webapps
\
examples by default).




Fig. 28


Virtual Directory Alias


Fig. 29


Virtual Directory Path


Fig. 30


Virtual Directory Access Permissions

Click “Next” to complete the installation.

Now,

when you browse to http://localhost/examples/index.html, you should see the following page
display. Now that IIS can find the physical path, it can pass the request to the ISAPI filter, and
Tomcat can return the pages.


F
ig. 31
-

Tomcat examples page

Now that the example pages are working, you might want to add some of your own .JSP code to the
IIS web instance. If you
create a
\
JTest folder in your web root and put some sample files there (I
copied the
basic
-
arithmetic.jsp

file from the Tomcat examples to the JTest folder for my test.), the
URI http://localhost/jtest/mytest.jsp will not work (yet). That is because “.jsp
” is not a valid mime
time for IIS, so IIS simply reports that it can’t find (deal with) the file. Older versions of IIS would
have displayed the source of the file, using a default Text mime type.

Remember the
uriworkermap.properties

file? It only has a r
eference to the /examples path


assigned to Worker1. Add the following lines to it so references to /jtest can be assigned to a worker:

/jtest/*=worker1

/jtest/*.jsp=worker1

Refresh your browser and you should see a different error message. This message n
ow comes from
Tomcat instead of IIS, proving that the redirector is now assigning the work to Worker1.


Fig. 32


Tomcat error page

You are seeing this error for the same reason that IIS presented 404 errors for the /examples path
earlier. You created the /jtest folder in the IIS

physical path


this time Tomcat is not aware of it! We
need to edit the
server.xml

file to tell Tomcat how to reference this path.

Open
server.xml
, look for your <host> definition. The Tomcat sample file will look something like
this:



<Host name="l
ocalhost"


appBase="webapps"



unpackWARs="true" autoDeploy="true"



xmlValidation="false" xmlNamespaceAware="false">

Add this line to tell Tomcat how to map references to the /jtest path:



<Context path="/jtest" docBase="e:
\
\
web
files
\
\
ltu
\
\
web
\
\
jtest"></Context>

Restart Tomcat and refresh your browser window


http://localhost/jtest/mytest.jsp should now
properly display the page!

Summary

The key to integrating IIS and Tomcat is recognizing that you actually have two web servers
running. Requests are sent first to IIS, which must forward (redirect) them to the Tomcat web server.
It does this by invoking the redirector, which scans the request and decides whether it should
forward the request to Tomcat. If it does, Tomcat handles t
he request, otherwise, IIS handles it. The
redirector (and Tomcat) make the decision to handle the request only if key criteria are met.



Is it a .JSP or Servlet file?



Is a worker available for the URI?

Another important point to remember is that web server
s translate the logical web paths to physical
disk paths. If the logical path of the web server can’t reach the physical path, you’ll get a 404 error.
This means that if you try to access content in one web server’s physical path from the other web
server,

you better have some kind of configuration defined that allows that. For IIS, it means
defining a Virtual Directory to map the web logical path to a physical folder. For Tomcat, you need
to define the <Context> in
server.xml

to accomplish the same thing.

Be aware that for my testing, I copied specific files


basic
-
arithmetic.jsp


to my jtest folder in IIS
because it had no dependencies on other files. You can’t do this with many of the other examples
because they reference external files and java beans t
hat haven’t been mapped in IIS. This is
certainly possible, but was more than I wanted to present in a basic example.