~ubuntu-branches/ubuntu/oneiric/libapache-mod-jk/oneiric

« back to all changes in this revision

Viewing changes to docs/howto/iis.html

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2006-08-05 16:30:53 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060805163053-myf66gm6j1a21ps6
Tags: 1:1.2.18-1ubuntu1
Merge from Debian unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Tomcat Connector - IIS HowTo</title><meta value="Henri Gomez" name="author"><meta value="hgomez@apache.org" name="email"><meta value="Gal Shachor" name="author"><meta value="shachor@il.ibm.com" name="email"><meta value="Yoav Shapira" name="author"><meta value="yoavs@apache.org" name="email"><link rel="stylesheet" type="text/css" href="../style.css"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="4" width="100%" border="0"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="Apache Tomcat" align="left" src="../images/tomcat.gif"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="http://www.apache.org/images/asf-logo.gif"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Generic Howto</strong></p><ul><li><a href="quick.html">For the impatient</a></li><li><a href="workers.html">All about workers</a></li><li><a href="loadbalancers.html">Load Balancing</a></li></ul><p><strong>Webservers</strong></p><ul><li><a href="apache.html">Apache</a></li><li><a href="iis.html">IIS</a></li><li><a href="domino.html">Domino</a></li><li><a href="nes.html">SunOne (Netscape)</a></li></ul><p><strong>Get Involved</strong></p><ul><li><a href="doccontrib.html">Contribute documentation</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Tomcat Connector</h1><h2>IIS HowTo</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/iis.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
 
2
                    </a></small></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
 
3
<p>
 
4
This document explains how to set up IIS to cooperate with Tomcat. 
 
5
</p>
 
6
 
 
7
<p>
 
8
Normally IIS can not execute Servlets and Java Server Pages (JSPs), 
 
9
configuring IIS to use the JK ISAPI redirector plugin will let IIS send servlet and 
 
10
JSP requests to Tomcat (and this way, serve them to clients).
 
11
</p>
 
12
 
 
13
<p>
 
14
It is recommanded that you also read the <a href="workers.html">Workers HowTo</a> document
 
15
to learn how to setup the working entities between your WebServer and Tomcat Engines.
 
16
</p>
 
17
 
 
18
 
 
19
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Document Conventions and Assumptions"><strong>Document Conventions and Assumptions</strong></a></font></td></tr><tr><td><blockquote>
 
20
<p>
 
21
${tomcat_home} is the root directory of tomcat. 
 
22
Your Tomcat installation should have the following subdirectories:
 
23
 
 
24
<ul>
 
25
<li>
 
26
${tomcat_home}\conf - Where you can place various configuration files
 
27
</li>
 
28
<li>
 
29
${tomcat_home}\webapps - Containing example applications
 
30
</li>
 
31
<li>
 
32
${tomcat_home}\bin - Where you place web server plugins
 
33
</li>
 
34
</ul>
 
35
</p>
 
36
<p>
 
37
In all the examples in this document ${tomcat_home} will be <b>c:\tomcat</b>.
 
38
A worker is defined to be a tomcat process that accepts work from the IIS server.
 
39
</p>
 
40
</blockquote></td></tr></table>
 
41
 
 
42
 
 
43
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Supported Configuration"><strong>Supported Configuration</strong></a></font></td></tr><tr><td><blockquote>
 
44
<p>
 
45
The IIS-Tomcat redirector was developed and tested on:
 
46
<ul>
 
47
<li>
 
48
WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98
 
49
</li>
 
50
<li>
 
51
IIS4.0 and PWS4.0 (numerous people have working IIS 5 and IIS 6 configurations)
 
52
</li>
 
53
<li>
 
54
Tomcat 3.2 and later, Tomcat 4.x and Tomcat 5
 
55
</li>
 
56
</ul>
 
57
</p>
 
58
 
 
59
<p>
 
60
The redirector uses <b>ajp12</b> and <b>ajp13</b> to send requests to the Tomcat containers. There is also an option to use Tomcat in process, 
 
61
more about the in-process mode can be found in the in process howto.
 
62
</p>
 
63
</blockquote></td></tr></table>
 
64
 
 
65
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="IIS 5 and 6 Notes"><strong>IIS 5 and 6 Notes</strong></a></font></td></tr><tr><td><blockquote>
 
66
<p>
 
67
There are extra steps you need to take for configuring Tomcat with IIS 5 and 6.  Please see the appropriate links from 
 
68
<a href="http://wiki.apache.org/tomcat/Tomcat/Links">Tomcat Useful Links</a>.
 
69
</p>
 
70
</blockquote></td></tr></table>
 
71
 
 
72
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Who support ajp protocols ?"><strong>Who support ajp protocols ?</strong></a></font></td></tr><tr><td><blockquote>
 
73
<p>
 
74
The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x.
 
75
</p>
 
76
 
 
77
<p>
 
78
The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead 
 
79
<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x and 5.
 
80
</p>
 
81
 
 
82
<p>
 
83
Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol.
 
84
</p>
 
85
 
 
86
<p>
 
87
Others servlet engines such as <b>jetty</b> have support for ajp13 protocol
 
88
</p>
 
89
 
 
90
</blockquote></td></tr></table>
 
91
 
 
92
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="How does it work ?"><strong>How does it work ?</strong></a></font></td></tr><tr><td><blockquote>
 
93
<p>
 
94
<ol>
 
95
<li>
 
96
The IIS-Tomcat redirector is an IIS plugin (filter + extension), IIS load the redirector plugin and calls its 
 
97
filter function for each in-coming request.
 
98
</li>
 
99
<li>
 
100
The filter then tests the request URL against a list of URI-paths held inside uriworkermap.properties, 
 
101
If the current request matches one of the entries in the list of URI-paths, 
 
102
the filter transfer the request to the extension.
 
103
</li>
 
104
<li>
 
105
The extension collects the request parameters and forwards them to the appropriate worker using the defined
 
106
protocol like <b>ajp13</b>.
 
107
</li>
 
108
<li>
 
109
The extension collects the response from the worker and returns it to the browser.
 
110
</li>
 
111
</ol>
 
112
</p>
 
113
</blockquote></td></tr></table>
 
114
 
 
115
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
 
116
<p>
 
117
A pre-built version of the ISAPI redirector server plugin, isapi_redirect.dll, is available under 
 
118
the win32/i386 directory of tomcat-connectors distribution. 
 
119
For those using Netscape as your browser, try downloading a zip version of the file, if available. 
 
120
There can be problems using Netscape to download DLL files.
 
121
 
 
122
You can also build a copy locally from the source present in tomcat-connectors distribution.
 
123
 
 
124
The Tomcat redirector requires three entities:
 
125
 
 
126
<ul>
 
127
<li>
 
128
<b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section).
 
129
</li>
 
130
<li>
 
131
<b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). 
 
132
A sample workers.properties can be found under the conf directory.
 
133
</li>
 
134
<li>
 
135
<b>uriworkermap.properties</b> - A file that maps URL-Path patterns to workers. 
 
136
A sample uriworkermap.properties can be found under the conf directory as well.
 
137
</li>
 
138
</ul>
 
139
</p>
 
140
 
 
141
<p>
 
142
The installation includes the following parts:
 
143
 
 
144
<ul>
 
145
<li>
 
146
Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS.
 
147
</li>
 
148
<li>
 
149
Adding more contexts to the configuration.
 
150
</li>
 
151
</ul>
 
152
</p>
 
153
 
 
154
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuring the ISAPI Redirector"><strong>Configuring the ISAPI Redirector</strong></a></font></td></tr><tr><td><blockquote>
 
155
<p>
 
156
In this document I will assume that isapi_redirect.dll is placed in 
 
157
<b>c:\tomcat\bin\win32\i386\isapi_redirect.dll</b> and 
 
158
that you created the properties files are in <b>c:\tomcat\conf</b>.
 
159
</p>
 
160
<p>
 
161
<ol>
 
162
<li>
 
163
In the registry, create a new registry key named
 
164
<b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b>
 
165
</li>
 
166
<li>
 
167
Add a string value with the name <b>extension_uri</b> and a value of <b>/jakarta/isapi_redirect.dll</b>
 
168
</li>
 
169
<li>
 
170
Add a string value with the name <b>log_file</b> and a value pointing to where you want your 
 
171
log file to be (for example <b>c:\tomcat\logs\isapi.log</b>).
 
172
</li>
 
173
<li>
 
174
Add a string value with the name <b>log_level</b> and a value for your log level 
 
175
(can be debug, info, error or emerg).
 
176
</li>
 
177
<li>
 
178
Add a string value with the name <b>worker_file</b> and a value which is the full path 
 
179
to your workers.properties file (for example <b>c:\tomcat\conf\workers.properties</b>)
 
180
</li>
 
181
<li>
 
182
Add a string value with the name <b>worker_mount_file</b> and a value which is the full path 
 
183
to your uriworkermap.properties file (for example <b>c:\tomcat\conf\uriworkermap.properties</b>)
 
184
</li>
 
185
<li>
 
186
Using the IIS management console, add a new virtual directory to your IIS/PWS web site.
 
187
The name of the virtual directory must be jakarta. 
 
188
Its physical path should be the directory where you placed isapi_redirect.dll 
 
189
(in our example it is c:\tomcat\bin\win32\i386). 
 
190
While creating this new virtual directory assign it with execute access.
 
191
</li>
 
192
<li>
 
193
Using the IIS management console, add isapi_redirect.dll as a filter in your IIS/PWS web site. 
 
194
The name of the filter should reflect its task (I use the name tomcat), 
 
195
its executable must be our c:\tomcat\bin\win32\i386\isapi_redirect.dll. 
 
196
For PWS, you'll need to use regedit and add/edit the <b>"Filter DLLs"</b> key under 
 
197
<b>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters</b>. 
 
198
This key contains a "," separated list of dlls ( full paths ) - 
 
199
you need to insert the full path to isapi_redirect.dll.
 
200
</li>
 
201
<li>
 
202
Restart IIS (stop + start the IIS service), make sure that the tomcat filter is marked with a green up-pointing arrow.
 
203
Under Win98 you may need to <b>cd WINDOWS\SYSTEM\inetsrv</b> and type PWS /stop 
 
204
( the DLL and log files are locked - even if you click the stop button, 
 
205
PWS will still keep the DLLs in memory. ). Type pws to start it again.
 
206
</li>
 
207
</ol>
 
208
</p>
 
209
<p>
 
210
That's all, you should now start Tomcat and ask IIS to serve you the /examples context. 
 
211
Try <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> for example and 
 
212
execute some of the JSP examples. 
 
213
</p>
 
214
<p>
 
215
If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem.
 
216
</p>
 
217
 
 
218
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Adding additional Contexts"><strong>Adding additional Contexts</strong></a></font></td></tr><tr><td><blockquote>
 
219
<p>
 
220
The examples context is useful for verifying your installation, 
 
221
but you will also need to add your own contexts. Adding a new context requires two operations:
 
222
</p>
 
223
<p>
 
224
<ol>
 
225
<li>
 
226
Adding the context to Tomcat (I am not going to talk about this).
 
227
</li>
 
228
<li>
 
229
Adding the context to the ISAPI redirector.
 
230
</li>
 
231
</ol>
 
232
</p>
 
233
<p>
 
234
Adding a context to the ISAPI redirector is simple, all you need to do is to edit 
 
235
your uriworkermap.properties and to add a line that looks like:
 
236
</p>
 
237
 
 
238
<div class="example"><pre>
 
239
  /context/*=worker_name
 
240
</pre></div>
 
241
 
 
242
<p>
 
243
Workers and their name are defined in workers.properties, by default workers.properties comes 
 
244
with a single pre-configured worker named <b>"defworker"</b> so you can use it. 
 
245
As an example, if you want to add a context named "shop", the line that you should add to 
 
246
uriworkermap.properties will be:
 
247
</p>
 
248
 
 
249
<div class="example"><pre>
 
250
  /shop/*=defworker
 
251
</pre></div>
 
252
 
 
253
After saving uriworkermap.properties restart IIS and it will serve the new context.
 
254
 
 
255
<p>
 
256
A feature is present till Tomcat 3.2, where a uriworkermap.properties-auto is automatically 
 
257
written each time Tomcat is started. This file includes settings for each of the contexts that 
 
258
Tomcat will serve during its run. 
 
259
</p>
 
260
<p>
 
261
Each context has settings to have Tomcat handle servlet and JSP requests, 
 
262
but by default static content is left to be served by IIS. 
 
263
</p>
 
264
<p>
 
265
Each context also has a commented out setting to have Tomcat handle all requests to the context. 
 
266
You can rename this file (so it won't be overwritten the next time Tomcat is started) and 
 
267
uncomment this setting or make other customizations. 
 
268
</p>
 
269
<p>
 
270
You may also use this file as is in your worker_mount_file setting.
 
271
</p>
 
272
</blockquote></td></tr></table>
 
273
 
 
274
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Advanced Context Configuration"><strong>Advanced Context Configuration</strong></a></font></td></tr><tr><td><blockquote>
 
275
<p>
 
276
Sometimes it is better to have IIS serve the static pages (html, gif, jpeg etc.) 
 
277
even if these files are part of a context served by Tomcat. 
 
278
</p>
 
279
<p>
 
280
For example, consider the html and gif files in the examples context, there is no need 
 
281
to serve them from the Tomcat process, IIS will suffice.
 
282
</p>
 
283
 
 
284
<p>
 
285
Making IIS serve static files that are part of the Tomcat contexts requires the following:
 
286
<ol>
 
287
<li>
 
288
Configuring IIS to know about the Tomcat contexts
 
289
</li>
 
290
<li>
 
291
Configuring the redirector to leave the static files for IIS
 
292
</li>
 
293
</ol>
 
294
</p>
 
295
 
 
296
<p>
 
297
Adding a Tomcat context to IIS requires the addition of a new IIS virtual directory that covers the Tomcat context. 
 
298
For example adding a /example IIS virtual directory that covers the c:\tomcat\webapps\examples directory.
 
299
</p>
 
300
 
 
301
<p>
 
302
Configuring the redirector is somewhat harder, you will need to specify the exact 
 
303
URL-Path pattern(s) that you want Tomcat to handle (usually only JSP files and servlets). 
 
304
This requires a change to the uriworkermap.properties : 
 
305
 
 
306
<div class="example"><pre>
 
307
  For the examples context it requires to replace the following line
 
308
  /examples/*=defworker
 
309
  with the following two lines
 
310
  /examples/*.jsp=defworker
 
311
  /examples/servlet/*=defworker
 
312
</pre></div>
 
313
</p>
 
314
 
 
315
<p>
 
316
As you can see the second configuration is more explicit, it actually instruct the redirector 
 
317
to redirect only requests to resources under /examples/servlet/ and resources under /examples/ 
 
318
whose name ends with .jsp. 
 
319
This is similar to what is automically written to the uriworkermap.properties-auto file for each context.
 
320
</p>
 
321
 
 
322
<p>
 
323
You can even be more explicit and provide lines such as:
 
324
 
 
325
<div class="example"><pre>
 
326
  /example/servletname=defworker
 
327
</pre></div>
 
328
</p>
 
329
 
 
330
<p>
 
331
that instructs the redirector to redirect request whose URL-Path equals /example/servletname 
 
332
to the worker named defworker.
 
333
</p>
 
334
 
 
335
</blockquote></td></tr></table>
 
336
 
 
337
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Protecting the WEB-INF Directory"><strong>Protecting the WEB-INF Directory</strong></a></font></td></tr><tr><td><blockquote>
 
338
<p>
 
339
Each servlet application (context) has a special directory named WEB-INF, 
 
340
this directory contains sensitive configurations data and Java classes and must be kept hidden from web users. 
 
341
Using the IIS management console it is possible to protect the WEB-INF directory from user access, 
 
342
this however requires the administrator to remember that. 
 
343
</p>
 
344
<p>
 
345
To avoid this need the redirector plugin automatically protects your WEB-INF directories by rejecting 
 
346
any request that contains WEB-INF in its URL-Path.
 
347
</p>
 
348
</blockquote></td></tr></table>
 
349
 
 
350
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Advanced Worker Configuration"><strong>Advanced Worker Configuration</strong></a></font></td></tr><tr><td><blockquote>
 
351
<p>
 
352
Sometimes you want to serve different contexts with different Tomcat processes 
 
353
(for example to spread the load among different machines). 
 
354
To achieve such goal you will need to define several workers and assign each context with its own worker.
 
355
</p>
 
356
<p>
 
357
Defining workers is done in workers.properties, this file includes two types of entries:
 
358
</p>
 
359
 
 
360
<p>
 
361
<div class="example"><pre>
 
362
  # An entry that lists all the workers defined
 
363
  worker.list=worker1, worker2
 
364
  # Entries that define the host and port associated with these workers
 
365
  worker.worker1.host=localhost
 
366
  worker.worker1.port=8009
 
367
  worker.worker1.type=ajp13
 
368
  worker.worker2.host=otherhost
 
369
  worker.worker2.port=8009
 
370
  worker.worker2.type=ajp13
 
371
</pre></div>
 
372
</p>
 
373
 
 
374
<p>
 
375
The above example defined two workers, now we can use these workers to serve two different contexts 
 
376
each with its own worker : 
 
377
<div class="example"><pre>
 
378
  example uriworkermap.properties fragment
 
379
  /examples/*=worker1
 
380
  /webpages/*=worker2
 
381
</pre></div>&gt;
 
382
</p>
 
383
 
 
384
<p>
 
385
As you can see the <b>examples</b> context is served by <b>worker1</b> while the 
 
386
<b>webpages</b> context is served by <b>worker2</b>.
 
387
</p>
 
388
 
 
389
<p>
 
390
More informations on using and configuring workers in the <a href="workers.html">Workers HowTO</a>
 
391
</p>
 
392
 
 
393
</blockquote></td></tr></table>
 
394
 
 
395
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Building ISAPI redirector"><strong>Building ISAPI redirector</strong></a></font></td></tr><tr><td><blockquote>
 
396
<p>
 
397
The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want 
 
398
to perform a custom build. You should also have IIS developer SDK
 
399
 
 
400
The steps that you need to take are:
 
401
<ul>
 
402
<li>
 
403
Change directory to the isapi plugins source directory.
 
404
</li>
 
405
<li>
 
406
Make the source with MSDEV
 
407
</li>
 
408
</ul>
 
409
<p class="screen"><div align="left"><table bgcolor="#000000" cellpadding="2" cellspacing="0" border="1" width="80%"><tr><td align="left" bgcolor="#000000"><div class="screen">Change directory to the isapi plugins source directory</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">cd c:\home\apache\jk\iis</b></nobr></code><br><div class="screen">Build the sources using MSDEV</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">MSDEV isapi.dsp /MAKE ALL</b></nobr></code><br></td></tr></table></div></p>
 
410
</p>
 
411
<p>
 
412
If msdev is not in your path, enter the full path to msdev.exe. 
 
413
This will build both release and debug versions of the redirector plugin.
 
414
An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and 
 
415
build it using the build menu.
 
416
</p>
 
417
</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Troubleshooting"><strong>Troubleshooting</strong></a></font></td></tr><tr><td><blockquote>
 
418
<p>
 
419
It is easy to have the ISAPI redirector not work the first time you try to install it.
 
420
</p>
 
421
<p>
 
422
If this happens to you, here are some steps to follow to try to correct the problem.
 
423
</p>
 
424
<p>
 
425
These steps aren't guaranteed to cover all possible problems, 
 
426
but they should help find the typical mistakes.
 
427
</p>
 
428
<p>
 
429
If you make any corrections during these steps, restart the IIS service as described above in the last step 
 
430
of the installation, then retry the step.
 
431
</p>
 
432
 
 
433
<p>To enable error tracking, make sure web site activity is being logged. 
 
434
For PWS 4.0 make sure "Save Web Site Activity Log" is checked in the Advanced Options of the Personal Web Manager.
 
435
</p>
 
436
   
 
437
<p>
 
438
Note: These steps assume your <b>worker_mount_file</b> setting points to an unmodified copy of the 
 
439
<b>uriworkermap.properties</b> file.<br>
 
440
Results may be misleading if <b>worker_mount_file</b> points to a modified <b>uriworkermap.properties</b>
 
441
or the <b>uriworkermap.properties-auto</b> file.<br>
 
442
It is also assumed that the <b>"/examples" context</b> works correcly if you access Tomcat directly.
 
443
</p>
 
444
 
 
445
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Win98"><strong>Win98</strong></a></font></td></tr><tr><td><blockquote>
 
446
<p>
 
447
Start the IIS service and Tomcat.
 
448
</p>
 
449
<p>
 
450
Check for the presence of the ISAPI redirector log file you specified in the log_file setting. 
 
451
If not found, verify the following:
 
452
</p>
 
453
<ul>
 
454
<li>
 
455
Check the "Filter DLLs" setting in the "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters" 
 
456
key and make sure the path is correct.
 
457
</li>
 
458
<li>
 
459
Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" key. 
 
460
Case isn't important, but an incorrect letter will prevent the isapi_redirect.dll from finding its registry settings.
 
461
</li>
 
462
<li>
 
463
Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists.
 
464
</li>
 
465
If the above are set correctly, the ISAPI redirector should be able to create the log file.
 
466
</ul>
 
467
<p>
 
468
Invoke the URL <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a>
 
469
in your browser. 
 
470
Case is important in Tomcat. The characters following "localhost" in the URL must be lower case. 
 
471
If the page fails to appear, stop the IIS service (required to view the IIS log file). 
 
472
Then examine the last line in the IIS log file in found in SYSTEM/LogFiles/W3SVC1 :
 
473
</p>
 
474
<p>
 
475
If the last line contains: 
 
476
</p>
 
477
<div class="example"><pre>
 
478
  GET "/examples/jsp/index.html HTTP/1.1" 404
 
479
</pre></div>
 
480
<p> 
 
481
then the ISAPI redirector is not recognizing that it should be handling requests for the "/examples" context. 
 
482
Check the following:
 
483
</p>
 
484
<ul>
 
485
<li>
 
486
Check the extension_uri name for typos.
 
487
</li>
 
488
<li>
 
489
Check the worker_file setting for typos, name and data.
 
490
</li>
 
491
<li>
 
492
Check the worker_mount_file setting typos, name and data.
 
493
</li>
 
494
If these are set correctly, the ISAPI redirector should recognize that it should handle requests for the "/examples" context.
 
495
</ul>
 
496
 
 
497
<p>If the last line contains something like:
 
498
</p>
 
499
 
 
500
<div class="example"><pre>
 
501
  GET "/jakarta/isapi_redirect.dll HTTP1.1"
 
502
</pre></div>
 
503
 
 
504
<p>
 
505
then the ISAPI redirector is recognizing that it should handle the request, 
 
506
but is not successful at getting Tomcat to service the request.
 
507
</p>
 
508
 
 
509
<p>
 
510
You should check the HTTP error code following GET "/..." :
 
511
</p>
 
512
 
 
513
<div class="example"><pre>
 
514
  Error 404
 
515
  GET "/..." 404
 
516
</pre></div>
 
517
 
 
518
<ul>
 
519
<li>
 
520
Make sure you entered the URL correctly.
 
521
</li>
 
522
<li>
 
523
Make sure the virtual directory created was called "jakarta". 
 
524
It should display in Personal Web Manager as "/jakarta" (without the quotes).
 
525
</li>
 
526
<li>
 
527
Make sure the extension_uri data begins with "/jakarta/" (without the quotes).
 
528
</li>
 
529
</ul>
 
530
 
 
531
<div class="example"><pre>
 
532
  Error 500
 
533
  GET "/..." 500
 
534
</pre></div>
 
535
 
 
536
<ul>
 
537
<li>
 
538
Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri setting.
 
539
</li>
 
540
<li>
 
541
Check the workers.properties file and make sure the port setting for worker.ajp12.port is the same as the port specified in the server.xml for the "Apache AJP12 support".
 
542
</li>
 
543
</ul>
 
544
 
 
545
<div class="example"><pre>
 
546
  Error 200 or 403
 
547
  GET "/..." 200
 
548
  GET "/..." 403
 
549
</pre></div>
 
550
 
 
551
<ul>
 
552
<li>
 
553
Make sure you have checked Execute Access 
 
554
for the jakarta virtual directory in the Advanced Options of the Personal Web Manager.
 
555
</li>
 
556
</ul>
 
557
 
 
558
<p>
 
559
If the above settings are correct, the index.html page should appear in your browser. 
 
560
You should also be able to click the Execute links to execute the JSP examples.
 
561
</p>
 
562
 
 
563
</blockquote></td></tr></table>
 
564
 
 
565
<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="WinNT/Win2K/WinXP"><strong>WinNT/Win2K/WinXP</strong></a></font></td></tr><tr><td><blockquote>
 
566
<p>
 
567
Start the World Wide Web Publishing Service and Tomcat.
 
568
</p>
 
569
<p>
 
570
Check for the presence of the ISAPI redirector log file you specified in the log_file setting. 
 
571
If not found, check the following:
 
572
</p>
 
573
<ul>
 
574
<li>
 
575
Check the "executable" you set for the filter in the IIS Management Console and make sure the path is correct.
 
576
</li>
 
577
<li>Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" key.
 
578
Case isn't important, but an incorrect letter will prevent the isapi_redirect.dll from finding its registry settings.
 
579
</li>
 
580
<li>
 
581
Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists.
 
582
</li>
 
583
If the above are set correctly, the ISAPI redirector should be able to create the log file.
 
584
</ul>
 
585
 
 
586
<p>
 
587
Check the tomcat filter you added and make sure its status shows a green upward-pointing arrow. 
 
588
If not, check the following:
 
589
</p>
 
590
<ul>
 
591
<li>
 
592
Check the worker_file setting for typos, name and data.
 
593
</li>
 
594
<li>
 
595
Check the worker_mount_file setting typos, name and data.
 
596
</li>
 
597
If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong.
 
598
</ul>
 
599
 
 
600
<p>
 
601
Invoke the URL <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> 
 
602
in your browser. Case is important in Tomcat. The characters following "localhost" in the URL must be lower case. 
 
603
If the page fails to appear, examine the last line in the IIS server log file in found in SYSTEM32/LogFiles/W3SVC1.
 
604
</p>
 
605
 
 
606
<p>
 
607
The last line should contain something like: GET "/jakarta/isapi_redirect.dll HTTP1.1", 
 
608
which indicates the ISAPI redirector is recognizing that it should handle the request.
 
609
</p>
 
610
 
 
611
<p>
 
612
You should check the HTTP error code following GET "/..." :
 
613
</p>
 
614
 
 
615
<div class="example"><pre>
 
616
  Error 404
 
617
  GET "/..." 404
 
618
</pre></div>
 
619
 
 
620
<ul>
 
621
<li>
 
622
Make sure you entered the URL correctly.
 
623
</li>
 
624
</ul>
 
625
 
 
626
<div class="example"><pre>
 
627
  Error 500
 
628
  GET "/..." 500
 
629
</pre></div>
 
630
 
 
631
<ul>
 
632
<li>
 
633
Make sure the virtual directory created was called "jakarta".
 
634
</li>
 
635
<li>
 
636
Make sure that the extension_uri setting is correct.
 
637
</li>
 
638
<li>
 
639
Check the workers.properties file and make sure the port setting for worker.ajp12.port is the same as the port specified in the server.xml for the "Apache AJP12 support".
 
640
</li>
 
641
</ul>
 
642
 
 
643
<div class="example"><pre>
 
644
  Error 200 or 403
 
645
  GET "/..." 200
 
646
  GET "/..." 403
 
647
</pre></div>
 
648
 
 
649
<ul>
 
650
<li>
 
651
Make sure you have checked Execute Access for the jakarta virtual directory in the 
 
652
Advanced Options of the Personal Web Manager.
 
653
</li>
 
654
</ul>
 
655
 
 
656
<p>
 
657
If the above settings are correct, the index.html page should appear in your browser. 
 
658
You should also be able to click the Execute links to execute the JSP examples.
 
659
</p>
 
660
</blockquote></td></tr></table>
 
661
 
 
662
 
 
663
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
 
664
        Copyright &copy; 1999-2005, Apache Software Foundation
 
665
        </em></font></div></td></tr></table></body></html>
 
 
b'\\ No newline at end of file'