rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml

   1 <?xml version="1.0"?>
   2 <!--
   3   Licensed to the Apache Software Foundation (ASF) under one or more
   4   contributor license agreements.  See the NOTICE file distributed with
   5   this work for additional information regarding copyright ownership.
   6   The ASF licenses this file to You under the Apache License, Version 2.0
   7   (the "License"); you may not use this file except in compliance with
   8   the License.  You may obtain a copy of the License at
   9
  10       http://www.apache.org/licenses/LICENSE-2.0
  11
  12   Unless required by applicable law or agreed to in writing, software
  13   distributed under the License is distributed on an "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15   See the License for the specific language governing permissions and
  16   limitations under the License.
  17 -->
  18 <!DOCTYPE document [
  19   <!ENTITY project SYSTEM "project.xml">
  20 ]>
  21 <document url="iis.html">
  22
  23     &project;
  24
  25     <properties>
  26         <author email="mturk@apache.org">Mladen Turk</author>
  27         <title>Configuring IIS</title>
  28     </properties>
  29
  30 <body>
  31
  32 <section name="Requirements">
  33 <p>
  34 The Tomcat redirector requires three entities:
  35
  36 <ul>
  37 <li>
  38 <b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section).
  39 </li>
  40 <li>
  41 <b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes).
  42 A sample workers.properties can be found under the conf directory.
  43 </li>
  44 <li>
  45 <b>uriworkermap.properties</b> - A file that maps URL-Path patterns to workers.
  46 A sample uriworkermap.properties can be found under the conf directory as well.
  47 </li>
  48 </ul>
  49 </p>
  50
  51 <p>
  52 The installation includes the following parts:
  53
  54 <ul>
  55 <li>
  56 Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS.
  57 </li>
  58 <li>
  59 Adding more contexts to the configuration.
  60 </li>
  61 </ul>
  62 </p>
  63 </section>
  64 <section name="Registry settings">
  65 <p>
  66 ISAPI redirector reads configuration from the registry, create a new registry key named :
  67 </p>
  68 <p>
  69 <b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b>
  70 </p>
  71 <attributes name="Key Name">
  72 <attribute name="extension_uri" required="true"><p>
  73 A string value pointing to the ISAPI extension <b>/jakarta/isapi_redirect.dll</b>
  74 </p></attribute>
  75 <attribute name="log_file" required="false"><p>
  76 A value pointing to location where log file will be created.
  77 (for example <b>c:\tomcat\logs\isapi.log</b>)
  78 <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.
  79 If the log file name includes any '%' characters, then it is treated as a format string for <code>strftime(3)</code>,
  80 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.
  81 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>
  82 </p></attribute>
  83 <attribute name="log_level" required="false"><p>
  84 A string value for log level
  85 (can be debug, info, warn, error or trace).</p>
  86 <p>This directive was added in version 1.2.31</p>
  87 </attribute>
  88 <attribute name="log_rotationtime" required="false"><p>
  89 The time between log file rotations in seconds.
  90 Setting this to 0 (the default) disables log rotation based on time.</p>
  91 <p>This directive was added in version 1.2.31</p>
  92 </attribute>
  93 <attribute name="log_filesize" required="false"><p>
  94 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.
  95 <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.
  96 <br/>If <b>log_rotationtime</b> is specified, then this setting is ignored.
  97 </p></attribute>
  98 <attribute name="worker_file" required="true"><p>
  99 A string value which is the full path to workers.properties file
 100 (for example <b>c:\tomcat\conf\workers.properties</b>)
 101 </p></attribute>
 102 <attribute name="worker_mount_file" required="true"><p>
 103 A string value which is the full path to uriworkermap.properties file
 104 (for example <b>c:\tomcat\conf\uriworkermap.properties</b>)
 105 </p></attribute>
 106 <attribute name="rewrite_rule_file" required="false"><p>
 107 A string value which is the full path to rewrite.properties file
 108 (for example <b>c:\tomcat\conf\rewrite.properties</b>)
 109 </p></attribute>
 110 <attribute name="shm_size" required="false"><p>
 111 A DWORD value size of the shared memory. Set this value to be
 112 the number of all defined workers * 400.
 113 (Set this value only if you have <b>more</b> then <b>64</b> workers)
 114 </p>
 115 <p>This directive has been added in version 1.2.20</p>
 116 <p>Starting with version 1.2.27 the size of the shared memory is determined
 117 automatically, even for large numbers of workers. This attribute is not
 118 needed any longer.</p>
 119 </attribute>
 120 <attribute name="worker_mount_reload" required="false"><p>
 121 A DWORD value specifying the time in seconds upon which the
 122 <b>worker_mount_file</b> will be reloaded.
 123 </p>
 124 <p>This directive has been added in version 1.2.20</p>
 125 </attribute>
 126 <attribute name="strip_session" required="false"><p>
 127 A string value representing a boolean. If it is set to true,
 128 URL session suffixes of the form ";jsessionid=..." get stripped of URLs,
 129 even if the are served locally by the web server.
 130 </p>
 131 <p>
 132 A true value can be represented by the string "1" or any string starting
 133 with the letters "T" or "t". A false value will be assumed for "0"
 134 or any string starting with "F" or "f". The default value is false.
 135 </p>
 136 <p>This directive has been added in version 1.2.21</p>
 137 </attribute>
 138 <attribute name="auth_complete" required="false"><p>
 139 A DWORD value representing "0" or "1". This is needed because
 140 of minor incompatibilities with IIS 5.1.
 141 </p>
 142 <p>
 143 By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE
 144 event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS.
 145 This might be needed for IIS 5.1 when handling requests using the
 146 PUT HTTP method.
 147 </p>
 148 <p>This directive has been added in version 1.2.21</p>
 149 </attribute>
 150 <attribute name="uri_select" required="false"><p>
 151 A string value which influences, how URIs are decoded and re-encoded
 152 between IIS and Tomcat. You should leave this at it's default value,
 153 unless you have a very good reason to change it.
 154 </p>
 155 <p>
 156 If the value is "parsed", the forwarded URI
 157 will be decoded and explicit path components like ".." will already
 158 be resolved. This is less spec compliant and is <b>not safe</b>
 159 if you are using prefix forwarding rules.
 160 </p>
 161 <p>
 162 If the value is "unparsed", the forwarded URI
 163 will be the original request URI. It's spec compliant and also
 164 the safest option. Rewriting the URI and then forwarding the rewritten
 165 URI will not work.
 166 </p>
 167 <p>
 168 If the value is "escaped", the forwarded URI
 169 will be the re-encoded form of the URI used by "parsed".
 170 Explicit path components like ".." will already be resolved.
 171 This will not work in combination with URL encoded session IDs.
 172 </p>
 173 <p>
 174 If the value is "proxy", the forwarded URI
 175 will be a partially re-encoded form of the URI used by "parsed".
 176 Explicit path components like ".." will already be resolved.
 177 and problematic are re-encoded.
 178 </p>
 179 <p>The default value since version 1.2.24 is "proxy". Before it was "parsed".</p>
 180 </attribute>
 181 <attribute name="reject_unsafe" required="false"><p>
 182 A string value representing a boolean. If it is set to true,
 183 URLs containing percent signs '%' or backslashes '\'
 184 after decoding will be rejected.
 185 </p>
 186 <p>
 187 Most web apps do not use such URLs. By enabling "reject_unsafe" you
 188 can block several well known URL encoding attacks.
 189 </p>
 190 <p>
 191 A true value can be represented by the string "1" or any string starting
 192 with the letters "T" or "t". A false value will be assumed for "0"
 193 or any string starting with "F" or "f". The default value is false.
 194 </p>
 195 <p>This directive has been added in version 1.2.24</p>
 196 </attribute>
 197 <attribute name="watchdog_interval" required="false"><p>
 198 A DWORD value representing the watchdog thread interval in seconds.
 199 The workers are maintained periodically by a background thread
 200 running periodically every watchdog_interval seconds. Worker maintenance
 201 checks for idle connections, corrects load status and is able
 202 to detect backend health status.
 203 </p>
 204 <p>
 205 The maintenance only happens, if since the last maintenance at
 206 least <a href="workers.html"><code>worker.maintain</code></a>
 207 seconds have passed. So setting the watchdog_interval
 208 much smaller than <code>worker.maintain</code> is not useful.
 209 </p>
 210 <p>
 211 The default value is 0 seconds, meaning the watchdog thread
 212 will not be created, and the maintenance is done in combination
 213 with normal requests instead.
 214 </p>
 215 <p>This directive has been added in version 1.2.27</p>
 216 </attribute>
 217 <attribute name="error_page" required="false"><p>
 218 A string value representing the error page url redirection when
 219 backend returns non-200 response. This directive can be used
 220 to customise the error messages returned from backend server.
 221 </p>
 222 <p>The url must point to a valid server url and can contain
 223 format string number <code>(%d)</code> that can be used to
 224 separate the pages by error number. The redirect url in that
 225 case is formatted by replacing <code>%d</code> from
 226 <code>error_page</code> to returned error number.
 227 </p>
 228 <p>This directive has been added in version 1.2.27</p>
 229 </attribute>
 230 <attribute name="enable_chunked_encoding" required="false"><p>
 231 A string value representing a boolean. If it is set to true,
 232 chunked encoding is supported by the server.
 233 </p>
 234 <p>
 235 A true value can be represented by the string "1" or any string starting
 236 with the letters "T" or "t". A false value will be assumed for "0"
 237 or any string starting with "F" or "f". The default value is false.
 238 </p>
 239 <warn>This option is considered experimental and its support
 240 must be compile time enabled. Use <code>isapi_redirect.dll</code>
 241 with chunked support enabled.
 242 </warn>
 243 <p>This directive has been added in version 1.2.27</p>
 244 </attribute>
 245 </attributes>
 246 </section>
 247 <section name="Using a properties file for configuration">
 248 <p>
 249 The ISAPI redirector can read it's configuration from a properties file instead of the registry.
 250 This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server.
 251 The redirector will check for the properties file during initialisation, and use it in preference to the registry if present.
 252 </p>
 253 <p>
 254 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.
 255 </p>
 256 <p>
 257 The property names and values in the properties file are the same as for the registry settings described above. For example:
 258 </p>
 259 <p>
 260 <source>
 261 # Configuration file for the Jakarta ISAPI Redirector
 262
 263 # The path to the ISAPI Redirector Extension, relative to the website
 264 # This must be in a virtual directory with execute privileges
 265 extension_uri=/jakarta/isapi_redirect.dll
 266
 267 # Full path to the log file for the ISAPI Redirector
 268 log_file=c:\tomcat\logs\isapi_redirect.log
 269
 270 # Log level (debug, info, warn, error or trace)
 271 log_level=info
 272
 273 # Full path to the workers.properties file
 274 worker_file=c:\tomcat\conf\workers.properties
 275
 276 # Full path to the uriworkermap.properties file
 277 worker_mount_file=c:\tomcat\conf\uriworkermap.properties
 278 </source>
 279 </p>
 280 <p>
 281     Notes:
 282     <ul>
 283         <li>
 284             Back-slashes - '\' - are not escape characters.
 285         </li>
 286         <li>
 287             Comment lines begin with '#'.
 288         </li>
 289     </ul>
 290 </p>
 291 <p>Starting with version 1.2.27 two environment variables are
 292 dynamically added to the environment that can be used inside
 293 <code>.properties</code> files.
 294     <ul>
 295         <li>JKISAPI_PATH - Full path to the ISAPI Redirector.
 296         </li>
 297         <li>JKISAPI_NAME - Name of the ISAPI Redirector dll without extension
 298         </li>
 299     </ul>
 300 </p>
 301 <p><source>
 302 # Use the logs in the installation path of ISAPI Redirector
 303 log_file=$(ISAPI_PATH)\$(ISAPI_NAME).log
 304 </source></p>
 305 </section>
 306
 307 <section name="Log file rotation">
 308 <p>
 309 The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the
 310 <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> program provided with Apache HTTP Server.
 311 </p>
 312 <p>
 313 To configure log rotation, configure a <b>log_file</b>, and one of the <b>log_rotationtime</b> or <b>log_filesize</b> options.
 314 If both are specified, the <b>log_rotationtime</b> will take precedence, and <b>log_filesize</b> will be ignored.
 315 <br/>For example, to configure daily rotation of the log file:
 316 </p>
 317 <source>
 318 # Configuration file for the Jakarta ISAPI Redirector
 319 ...
 320
 321 # Full path to the log file for the ISAPI Redirector
 322 log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log
 323
 324 # Log level (debug, info, warn, error or trace)
 325 log_level=info
 326
 327 # Rotate the log file every day
 328 log_rotationtime=86400
 329
 330 ...
 331 </source>
 332 <p>
 333 Or to configure rotation of the log file when it reaches 5MB in size:
 334 </p>
 335 <source>
 336 # Configuration file for the Jakarta ISAPI Redirector
 337 ...
 338
 339 # Full path to the log file for the ISAPI Redirector
 340 log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log
 341
 342 # Log level (debug, info, warn, error or trace)
 343 log_level=info
 344
 345 # Rotate the log file at 5 MB
 346 log_filesize=5M
 347
 348 ...
 349 </source>
 350 <p>
 351 The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure
 352  a log file name with <code>strftime(3)</code> format codes in it, then ensure it specifies the same granularity
 353  as the rotation time configured, e.g. <b>%Y-%m-%d</b> if rotating daily (<b>log_rotationtime=86400</b>).
 354 <br/>See the <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> documentation for more examples.
 355 </p>
 356
 357 </section>
 358
 359 <section name="Using a simple rewrite rules">
 360 <p>
 361 The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not
 362 as powerful as Apache Httpd's mod_rewrite, it allows a simple exchange of request URIs
 363 </p>
 364 <p>
 365 The rule is in the form original-url-prefix=forward-url-prefix. For example:
 366 </p>
 367 <source>
 368 # Simple rewrite rules, making /jsp-examples
 369 # and /servlets-examples available under shorter URLs
 370 /jsp/=/jsp-examples/
 371 /servlets/=/servlets-examples/
 372 </source>
 373 <p>
 374 You can also use regular expressions, if you prefix the rule with a tilde <code>~</code>:
 375 </p>
 376 <source>
 377 # Complex rewrite rule, adding "-examples"
 378 # to the first path component of all requests
 379 ~/([^/]*)=/$1-examples
 380 </source>
 381 <p>
 382 Note that uriworkermap.properties must use the URLs before rewriting.
 383 </p>
 384 </section>
 385
 386 </body>
 387 </document>