1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Reference Guide - Configuring IIS</title><meta name="author" value="Mladen Turk"><meta name="email" value="mturk@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - Reference Guide</h1><h2>Configuring IIS</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Requirements"><strong>Requirements</strong></a></font></td></tr><tr><td><blockquote>
<p>
The Tomcat redirector requires three entities:
<ul>
<li>
<b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section).
</li>
<li>
<b>workers.properties</b> - 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.
</li>
<li>
<b>uriworkermap.properties</b> - A file that maps URL-Path patterns to workers.
A sample uriworkermap.properties can be found under the conf directory as well.
</li>
</ul>
</p>
<p>
The installation includes the following parts:
<ul>
<li>
Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS.
</li>
<li>
Adding more contexts to the configuration.
</li>
</ul>
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Registry settings"><strong>Registry settings</strong></a></font></td></tr><tr><td><blockquote>
<p>
ISAPI redirector reads configuration from the registry, create a new registry key named :
</p>
<p>
<b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b>
</p>
<table border="1" cellpadding="5"><tr><th width="20%" bgcolor="#023264"><font color="#ffffff">Key Name</font></th><th width="80%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>extension_uri</code></strong></td><td align="left" valign="center"><p>
A string value pointing to the ISAPI extension <b>/jakarta/isapi_redirect.dll</b>
</p></td></tr><tr><td align="left" valign="center"><code>log_file</code></td><td align="left" valign="center"><p>
A value pointing to location where log file will be created.
(for example <b>c:\tomcat\logs\isapi.log</b>)
<br>If one of the log rotation settings (<b>log_rotationtime</b> or <b>log_filesize</b>) are specified then the actual log file name is based on this setting.
If the log file name includes any '%' characters, then it is treated as a format string for <b class="code">strftime(3)</b>,
e.g. <b>c:\tomcat\logs\isapi-%Y-%m-%d-%H_%M_%S.log</b>. Otherwise, the suffix <em>.nnnnnnnnnn</em> is automatically added and is the time in seconds.
A full list of format string substitutions can be found in the <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">Apache rotatelogs documentation</a>
</p></td></tr><tr><td align="left" valign="center"><code>log_level</code></td><td align="left" valign="center"><p>
A string value for log level
(can be debug, info, warn, error or trace).</p>
<p>This directive was added in version 1.2.31</p>
</td></tr><tr><td align="left" valign="center"><code>log_rotationtime</code></td><td align="left" valign="center"><p>
The time between log file rotations in seconds.
Setting this to 0 (the default) disables log rotation based on time.</p>
<p>This directive was added in version 1.2.31</p>
</td></tr><tr><td align="left" valign="center"><code>log_filesize</code></td><td align="left" valign="center"><p>
The maximum log file size in megabytes, after which the log file will be rotated. Setting this to 0 (the default) disables log rotation based on file size.
<br>The value can have an optional <b>M</b> suffix, i.e. both <b>5</b> and <b>5M</b> will rotate the log file when it grows to 5MB.
<br>If <b>log_rotationtime</b> is specified, then this setting is ignored.
</p></td></tr><tr><td align="left" valign="center"><strong><code>worker_file</code></strong></td><td align="left" valign="center"><p>
A string value which is the full path to workers.properties file
(for example <b>c:\tomcat\conf\workers.properties</b>)
</p></td></tr><tr><td align="left" valign="center"><strong><code>worker_mount_file</code></strong></td><td align="left" valign="center"><p>
A string value which is the full path to uriworkermap.properties file
(for example <b>c:\tomcat\conf\uriworkermap.properties</b>)
</p></td></tr><tr><td align="left" valign="center"><code>rewrite_rule_file</code></td><td align="left" valign="center"><p>
A string value which is the full path to rewrite.properties file
(for example <b>c:\tomcat\conf\rewrite.properties</b>)
</p></td></tr><tr><td align="left" valign="center"><code>shm_size</code></td><td align="left" valign="center"><p>
A DWORD value size of the shared memory. Set this value to be
the number of all defined workers * 400.
(Set this value only if you have <b>more</b> then <b>64</b> workers)
</p>
<p>This directive has been added in version 1.2.20</p>
<p>Starting with version 1.2.27 the size of the shared memory is determined
automatically, even for large numbers of workers. This attribute is not
needed any longer.</p>
</td></tr><tr><td align="left" valign="center"><code>worker_mount_reload</code></td><td align="left" valign="center"><p>
A DWORD value specifying the time in seconds upon which the
<b>worker_mount_file</b> will be reloaded.
</p>
<p>This directive has been added in version 1.2.20</p>
</td></tr><tr><td align="left" valign="center"><code>strip_session</code></td><td align="left" valign="center"><p>
A string value representing a boolean. If it is set to true,
URL session suffixes of the form ";jsessionid=..." get stripped of URLs,
even if the are served locally by the web server.
</p>
<p>
A true value can be represented by the string "1" or any string starting
with the letters "T" or "t". A false value will be assumed for "0"
or any string starting with "F" or "f". The default value is false.
</p>
<p>This directive has been added in version 1.2.21</p>
</td></tr><tr><td align="left" valign="center"><code>auth_complete</code></td><td align="left" valign="center"><p>
A DWORD value representing "0" or "1". This is needed because
of minor incompatibilities with IIS 5.1.
</p>
<p>
By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE
event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS.
This might be needed for IIS 5.1 when handling requests using the
PUT HTTP method.
</p>
<p>This directive has been added in version 1.2.21</p>
</td></tr><tr><td align="left" valign="center"><code>uri_select</code></td><td align="left" valign="center"><p>
A string value which influences, how URIs are decoded and re-encoded
between IIS and Tomcat. You should leave this at it's default value,
unless you have a very good reason to change it.
</p>
<p>
If the value is "parsed", the forwarded URI
will be decoded and explicit path components like ".." will already
be resolved. This is less spec compliant and is <b>not safe</b>
if you are using prefix forwarding rules.
</p>
<p>
If the value is "unparsed", the forwarded URI
will be the original request URI. It's spec compliant and also
the safest option. Rewriting the URI and then forwarding the rewritten
URI will not work.
</p>
<p>
If the value is "escaped", the forwarded URI
will be the re-encoded form of the URI used by "parsed".
Explicit path components like ".." will already be resolved.
This will not work in combination with URL encoded session IDs.
</p>
<p>
If the value is "proxy", the forwarded URI
will be a partially re-encoded form of the URI used by "parsed".
Explicit path components like ".." will already be resolved.
and problematic are re-encoded.
</p>
<p>The default value since version 1.2.24 is "proxy". Before it was "parsed".</p>
</td></tr><tr><td align="left" valign="center"><code>reject_unsafe</code></td><td align="left" valign="center"><p>
A string value representing a boolean. If it is set to true,
URLs containing percent signs '%' or backslashes '\'
after decoding will be rejected.
</p>
<p>
Most web apps do not use such URLs. By enabling "reject_unsafe" you
can block several well known URL encoding attacks.
</p>
<p>
A true value can be represented by the string "1" or any string starting
with the letters "T" or "t". A false value will be assumed for "0"
or any string starting with "F" or "f". The default value is false.
</p>
<p>This directive has been added in version 1.2.24</p>
</td></tr><tr><td align="left" valign="center"><code>watchdog_interval</code></td><td align="left" valign="center"><p>
A DWORD value representing the watchdog thread interval in seconds.
The workers are maintained periodically by a background thread
running periodically every watchdog_interval seconds. Worker maintenance
checks for idle connections, corrects load status and is able
to detect backend health status.
</p>
<p>
The maintenance only happens, if since the last maintenance at
least <a href="workers.html"><b class="code">worker.maintain</b></a>
seconds have passed. So setting the watchdog_interval
much smaller than <b class="code">worker.maintain</b> is not useful.
</p>
<p>
The default value is 0 seconds, meaning the watchdog thread
will not be created, and the maintenance is done in combination
with normal requests instead.
</p>
<p>This directive has been added in version 1.2.27</p>
</td></tr><tr><td align="left" valign="center"><code>error_page</code></td><td align="left" valign="center"><p>
A string value representing the error page url redirection when
backend returns non-200 response. This directive can be used
to customise the error messages returned from backend server.
</p>
<p>The url must point to a valid server url and can contain
format string number <b class="code">(%d)</b> that can be used to
separate the pages by error number. The redirect url in that
case is formatted by replacing <b class="code">%d</b> from
<b class="code">error_page</b> to returned error number.
</p>
<p>This directive has been added in version 1.2.27</p>
</td></tr><tr><td align="left" valign="center"><code>enable_chunked_encoding</code></td><td align="left" valign="center"><p>
A string value representing a boolean. If it is set to true,
chunked encoding is supported by the server.
</p>
<p>
A true value can be represented by the string "1" or any string starting
with the letters "T" or "t". A false value will be assumed for "0"
or any string starting with "F" or "f". The default value is false.
</p>
<p><font color="#ff0000">This option is considered experimental and its support
must be compile time enabled. Use <b class="code">isapi_redirect.dll</b>
with chunked support enabled.
</font></p>
<p>This directive has been added in version 1.2.27</p>
</td></tr></table>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using a properties file for configuration"><strong>Using a properties file for configuration</strong></a></font></td></tr><tr><td><blockquote>
<p>
The ISAPI redirector can read it's configuration from a properties file instead of the registry.
This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server.
The redirector will check for the properties file during initialisation, and use it in preference to the registry if present.
</p>
<p>
Create a properties file in the same directory as the ISAPI redirector called <b>isapi_redirect.properties</b> i.e. with the same name as the ISAPI redirector DLL but with a <em>.properties</em> extension. A sample isapi_redirect.properties can be found under the conf directory.
</p>
<p>
The property names and values in the properties file are the same as for the registry settings described above. For example:
</p>
<p>
<div class="example"><pre>
# Configuration file for the Jakarta ISAPI Redirector
# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/jakarta/isapi_redirect.dll
# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\logs\isapi_redirect.log
# Log level (debug, info, warn, error or trace)
log_level=info
# Full path to the workers.properties file
worker_file=c:\tomcat\conf\workers.properties
# Full path to the uriworkermap.properties file
worker_mount_file=c:\tomcat\conf\uriworkermap.properties
</pre></div>
</p>
<p>
Notes:
<ul>
<li>
Back-slashes - '\' - are not escape characters.
</li>
<li>
Comment lines begin with '#'.
</li>
</ul>
</p>
<p>Starting with version 1.2.27 two environment variables are
dynamically added to the environment that can be used inside
<b class="code">.properties</b> files.
<ul>
<li>JKISAPI_PATH - Full path to the ISAPI Redirector.
</li>
<li>JKISAPI_NAME - Name of the ISAPI Redirector dll without extension
</li>
</ul>
</p>
<p><div class="example"><pre>
# Use the logs in the installation path of ISAPI Redirector
log_file=$(ISAPI_PATH)\$(ISAPI_NAME).log
</pre></div></p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Log file rotation"><strong>Log file rotation</strong></a></font></td></tr><tr><td><blockquote>
<p>
The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the
<a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> program provided with Apache HTTP Server.
</p>
<p>
To configure log rotation, configure a <b>log_file</b>, and one of the <b>log_rotationtime</b> or <b>log_filesize</b> options.
If both are specified, the <b>log_rotationtime</b> will take precedence, and <b>log_filesize</b> will be ignored.
<br>For example, to configure daily rotation of the log file:
</p>
<div class="example"><pre>
# Configuration file for the Jakarta ISAPI Redirector
...
# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log
# Log level (debug, info, warn, error or trace)
log_level=info
# Rotate the log file every day
log_rotationtime=86400
...
</pre></div>
<p>
Or to configure rotation of the log file when it reaches 5MB in size:
</p>
<div class="example"><pre>
# Configuration file for the Jakarta ISAPI Redirector
...
# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log
# Log level (debug, info, warn, error or trace)
log_level=info
# Rotate the log file at 5 MB
log_filesize=5M
...
</pre></div>
<p>
The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure
a log file name with <b class="code">strftime(3)</b> format codes in it, then ensure it specifies the same granularity
as the rotation time configured, e.g. <b>%Y-%m-%d</b> if rotating daily (<b>log_rotationtime=86400</b>).
<br>See the <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> documentation for more examples.
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using a simple rewrite rules"><strong>Using a simple rewrite rules</strong></a></font></td></tr><tr><td><blockquote>
<p>
The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not
as powerful as Apache Httpd's mod_rewrite, it allows a simple exchange of request URIs
</p>
<p>
The rule is in the form original-url-prefix=forward-url-prefix. For example:
</p>
<div class="example"><pre>
# Simple rewrite rules, making /jsp-examples
# and /servlets-examples available under shorter URLs
/jsp/=/jsp-examples/
/servlets/=/servlets-examples/
</pre></div>
<p>
You can also use regular expressions, if you prefix the rule with a tilde <b class="code">~</b>:
</p>
<div class="example"><pre>
# Complex rewrite rule, adding "-examples"
# to the first path component of all requests
~/([^/]*)=/$1-examples
</pre></div>
<p>
Note that uriworkermap.properties must use the URLs before rewriting.
</p>
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
Copyright © 1999-2011, Apache Software Foundation
</em></font></div></td></tr></table></body></html>
|
