rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/iis.html

   1 <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><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="true"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Reference Guide</strong></p><ul><li><a href="../reference/workers.html">workers.properties</a></li><li><a href="../reference/uriworkermap.html">uriworkermap.properties</a></li><li><a href="../reference/status.html">Status Worker</a></li><li><a href="../reference/apache.html">Apache HTTP Server</a></li><li><a href="../reference/iis.html">IIS</a></li></ul><p><strong>Generic HowTo</strong></p><ul><li><a href="../generic_howto/quick.html">For the impatient</a></li><li><a href="../generic_howto/workers.html">All about workers</a></li><li><a href="../generic_howto/timeouts.html">Timeouts</a></li><li><a href="../generic_howto/loadbalancers.html">Load Balancing</a></li><li><a href="../generic_howto/proxy.html">Reverse Proxy</a></li></ul><p><strong>Webserver HowTo</strong></p><ul><li><a href="../webserver_howto/apache.html">Apache HTTP Server</a></li><li><a href="../webserver_howto/iis.html">IIS</a></li><li><a href="../webserver_howto/nes.html">Netscape/SunOne/Sun</a></li></ul><p><strong>AJP Protocol Reference</strong></p><ul><li><a href="../ajp/ajpv13a.html">AJPv13</a></li><li><a href="../ajp/ajpv13ext.html">AJPv13 Extension Proposal</a></li></ul><p><strong>Miscellaneous Documentation</strong></p><ul><li><a href="../miscellaneous/faq.html">Frequently asked questions</a></li><li><a href="../miscellaneous/changelog.html">Changelog</a></li><li><a href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;product=Tomcat+Connectors&amp;long_desc_type=substring&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;keywords_type=allwords&amp;keywords=&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;emailassigned_to1=1&amp;emailtype1=substring&amp;email1=&amp;emailassigned_to2=1&amp;emailreporter2=1&amp;emailcc2=1&amp;emailtype2=substring&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=Reuse+same+sort+as+last+time&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=">Current Tomcat Connectors bugs</a></li><li><a href="../miscellaneous/doccontrib.html">Contribute documentation</a></li><li><a href="../miscellaneous/jkstatustasks.html">JK Status Ant Tasks</a></li><li><a href="../miscellaneous/reporttools.html">Reporting Tools</a></li><li><a href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html">Old JK/JK2 documentation</a></li></ul><p><strong>News</strong></p><ul><li><a href="../news/20110701.html">2011</a></li><li><a href="../news/20100101.html">2010</a></li><li><a href="../news/20090301.html">2009</a></li><li><a href="../news/20081001.html">2008</a></li><li><a href="../news/20070301.html">2007</a></li><li><a href="../news/20060101.html">2006</a></li><li><a href="../news/20050101.html">2005</a></li><li><a href="../news/20041100.html">2004</a></li></ul></td><!--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"><small><a href="printer/iis.html"><img src="../images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
   2                     </a></small></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>
   3 <p>
   4 The Tomcat redirector requires three entities:
   5
   6 <ul>
   7 <li>
   8 <b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section).
   9 </li>
  10 <li>
  11 <b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes).
  12 A sample workers.properties can be found under the conf directory.
  13 </li>
  14 <li>
  15 <b>uriworkermap.properties</b> - A file that maps URL-Path patterns to workers.
  16 A sample uriworkermap.properties can be found under the conf directory as well.
  17 </li>
  18 </ul>
  19 </p>
  20
  21 <p>
  22 The installation includes the following parts:
  23
  24 <ul>
  25 <li>
  26 Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS.
  27 </li>
  28 <li>
  29 Adding more contexts to the configuration.
  30 </li>
  31 </ul>
  32 </p>
  33 </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>
  34 <p>
  35 ISAPI redirector reads configuration from the registry, create a new registry key named :
  36 </p>
  37 <p>
  38 <b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b>
  39 </p>
  40 <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>
  41 A string value pointing to the ISAPI extension <b>/jakarta/isapi_redirect.dll</b>
  42 </p></td></tr><tr><td align="left" valign="center"><code>log_file</code></td><td align="left" valign="center"><p>
  43 A value pointing to location where log file will be created.
  44 (for example <b>c:\tomcat\logs\isapi.log</b>)
  45 <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.
  46 If the log file name includes any '%' characters, then it is treated as a format string for <b class="code">strftime(3)</b>,
  47 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.
  48 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>
  49 </p></td></tr><tr><td align="left" valign="center"><code>log_level</code></td><td align="left" valign="center"><p>
  50 A string value for log level
  51 (can be debug, info, warn, error or trace).</p>
  52 <p>This directive was added in version 1.2.31</p>
  53 </td></tr><tr><td align="left" valign="center"><code>log_rotationtime</code></td><td align="left" valign="center"><p>
  54 The time between log file rotations in seconds.
  55 Setting this to 0 (the default) disables log rotation based on time.</p>
  56 <p>This directive was added in version 1.2.31</p>
  57 </td></tr><tr><td align="left" valign="center"><code>log_filesize</code></td><td align="left" valign="center"><p>
  58 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.
  59 <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.
  60 <br>If <b>log_rotationtime</b> is specified, then this setting is ignored.
  61 </p></td></tr><tr><td align="left" valign="center"><strong><code>worker_file</code></strong></td><td align="left" valign="center"><p>
  62 A string value which is the full path to workers.properties file
  63 (for example <b>c:\tomcat\conf\workers.properties</b>)
  64 </p></td></tr><tr><td align="left" valign="center"><strong><code>worker_mount_file</code></strong></td><td align="left" valign="center"><p>
  65 A string value which is the full path to uriworkermap.properties file
  66 (for example <b>c:\tomcat\conf\uriworkermap.properties</b>)
  67 </p></td></tr><tr><td align="left" valign="center"><code>rewrite_rule_file</code></td><td align="left" valign="center"><p>
  68 A string value which is the full path to rewrite.properties file
  69 (for example <b>c:\tomcat\conf\rewrite.properties</b>)
  70 </p></td></tr><tr><td align="left" valign="center"><code>shm_size</code></td><td align="left" valign="center"><p>
  71 A DWORD value size of the shared memory. Set this value to be
  72 the number of all defined workers * 400.
  73 (Set this value only if you have <b>more</b> then <b>64</b> workers)
  74 </p>
  75 <p>This directive has been added in version 1.2.20</p>
  76 <p>Starting with version 1.2.27 the size of the shared memory is determined
  77 automatically, even for large numbers of workers. This attribute is not
  78 needed any longer.</p>
  79 </td></tr><tr><td align="left" valign="center"><code>worker_mount_reload</code></td><td align="left" valign="center"><p>
  80 A DWORD value specifying the time in seconds upon which the
  81 <b>worker_mount_file</b> will be reloaded.
  82 </p>
  83 <p>This directive has been added in version 1.2.20</p>
  84 </td></tr><tr><td align="left" valign="center"><code>strip_session</code></td><td align="left" valign="center"><p>
  85 A string value representing a boolean. If it is set to true,
  86 URL session suffixes of the form ";jsessionid=..." get stripped of URLs,
  87 even if the are served locally by the web server.
  88 </p>
  89 <p>
  90 A true value can be represented by the string "1" or any string starting
  91 with the letters "T" or "t". A false value will be assumed for "0"
  92 or any string starting with "F" or "f". The default value is false.
  93 </p>
  94 <p>This directive has been added in version 1.2.21</p>
  95 </td></tr><tr><td align="left" valign="center"><code>auth_complete</code></td><td align="left" valign="center"><p>
  96 A DWORD value representing "0" or "1". This is needed because
  97 of minor incompatibilities with IIS 5.1.
  98 </p>
  99 <p>
 100 By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE
 101 event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS.
 102 This might be needed for IIS 5.1 when handling requests using the
 103 PUT HTTP method.
 104 </p>
 105 <p>This directive has been added in version 1.2.21</p>
 106 </td></tr><tr><td align="left" valign="center"><code>uri_select</code></td><td align="left" valign="center"><p>
 107 A string value which influences, how URIs are decoded and re-encoded
 108 between IIS and Tomcat. You should leave this at it's default value,
 109 unless you have a very good reason to change it.
 110 </p>
 111 <p>
 112 If the value is "parsed", the forwarded URI
 113 will be decoded and explicit path components like ".." will already
 114 be resolved. This is less spec compliant and is <b>not safe</b>
 115 if you are using prefix forwarding rules.
 116 </p>
 117 <p>
 118 If the value is "unparsed", the forwarded URI
 119 will be the original request URI. It's spec compliant and also
 120 the safest option. Rewriting the URI and then forwarding the rewritten
 121 URI will not work.
 122 </p>
 123 <p>
 124 If the value is "escaped", the forwarded URI
 125 will be the re-encoded form of the URI used by "parsed".
 126 Explicit path components like ".." will already be resolved.
 127 This will not work in combination with URL encoded session IDs.
 128 </p>
 129 <p>
 130 If the value is "proxy", the forwarded URI
 131 will be a partially re-encoded form of the URI used by "parsed".
 132 Explicit path components like ".." will already be resolved.
 133 and problematic are re-encoded.
 134 </p>
 135 <p>The default value since version 1.2.24 is "proxy". Before it was "parsed".</p>
 136 </td></tr><tr><td align="left" valign="center"><code>reject_unsafe</code></td><td align="left" valign="center"><p>
 137 A string value representing a boolean. If it is set to true,
 138 URLs containing percent signs '%' or backslashes '\'
 139 after decoding will be rejected.
 140 </p>
 141 <p>
 142 Most web apps do not use such URLs. By enabling "reject_unsafe" you
 143 can block several well known URL encoding attacks.
 144 </p>
 145 <p>
 146 A true value can be represented by the string "1" or any string starting
 147 with the letters "T" or "t". A false value will be assumed for "0"
 148 or any string starting with "F" or "f". The default value is false.
 149 </p>
 150 <p>This directive has been added in version 1.2.24</p>
 151 </td></tr><tr><td align="left" valign="center"><code>watchdog_interval</code></td><td align="left" valign="center"><p>
 152 A DWORD value representing the watchdog thread interval in seconds.
 153 The workers are maintained periodically by a background thread
 154 running periodically every watchdog_interval seconds. Worker maintenance
 155 checks for idle connections, corrects load status and is able
 156 to detect backend health status.
 157 </p>
 158 <p>
 159 The maintenance only happens, if since the last maintenance at
 160 least <a href="workers.html"><b class="code">worker.maintain</b></a>
 161 seconds have passed. So setting the watchdog_interval
 162 much smaller than <b class="code">worker.maintain</b> is not useful.
 163 </p>
 164 <p>
 165 The default value is 0 seconds, meaning the watchdog thread
 166 will not be created, and the maintenance is done in combination
 167 with normal requests instead.
 168 </p>
 169 <p>This directive has been added in version 1.2.27</p>
 170 </td></tr><tr><td align="left" valign="center"><code>error_page</code></td><td align="left" valign="center"><p>
 171 A string value representing the error page url redirection when
 172 backend returns non-200 response. This directive can be used
 173 to customise the error messages returned from backend server.
 174 </p>
 175 <p>The url must point to a valid server url and can contain
 176 format string number <b class="code">(%d)</b> that can be used to
 177 separate the pages by error number. The redirect url in that
 178 case is formatted by replacing <b class="code">%d</b> from
 179 <b class="code">error_page</b> to returned error number.
 180 </p>
 181 <p>This directive has been added in version 1.2.27</p>
 182 </td></tr><tr><td align="left" valign="center"><code>enable_chunked_encoding</code></td><td align="left" valign="center"><p>
 183 A string value representing a boolean. If it is set to true,
 184 chunked encoding is supported by the server.
 185 </p>
 186 <p>
 187 A true value can be represented by the string "1" or any string starting
 188 with the letters "T" or "t". A false value will be assumed for "0"
 189 or any string starting with "F" or "f". The default value is false.
 190 </p>
 191 <p><font color="#ff0000">This option is considered experimental and its support
 192 must be compile time enabled. Use <b class="code">isapi_redirect.dll</b>
 193 with chunked support enabled.
 194 </font></p>
 195 <p>This directive has been added in version 1.2.27</p>
 196 </td></tr></table>
 197 </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>
 198 <p>
 199 The ISAPI redirector can read it's configuration from a properties file instead of the registry.
 200 This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server.
 201 The redirector will check for the properties file during initialisation, and use it in preference to the registry if present.
 202 </p>
 203 <p>
 204 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.
 205 </p>
 206 <p>
 207 The property names and values in the properties file are the same as for the registry settings described above. For example:
 208 </p>
 209 <p>
 210 <div class="example"><pre>
 211 # Configuration file for the Jakarta ISAPI Redirector
 212
 213 # The path to the ISAPI Redirector Extension, relative to the website
 214 # This must be in a virtual directory with execute privileges
 215 extension_uri=/jakarta/isapi_redirect.dll
 216
 217 # Full path to the log file for the ISAPI Redirector
 218 log_file=c:\tomcat\logs\isapi_redirect.log
 219
 220 # Log level (debug, info, warn, error or trace)
 221 log_level=info
 222
 223 # Full path to the workers.properties file
 224 worker_file=c:\tomcat\conf\workers.properties
 225
 226 # Full path to the uriworkermap.properties file
 227 worker_mount_file=c:\tomcat\conf\uriworkermap.properties
 228 </pre></div>
 229 </p>
 230 <p>
 231     Notes:
 232     <ul>
 233         <li>
 234             Back-slashes - '\' - are not escape characters.
 235         </li>
 236         <li>
 237             Comment lines begin with '#'.
 238         </li>
 239     </ul>
 240 </p>
 241 <p>Starting with version 1.2.27 two environment variables are
 242 dynamically added to the environment that can be used inside
 243 <b class="code">.properties</b> files.
 244     <ul>
 245         <li>JKISAPI_PATH - Full path to the ISAPI Redirector.
 246         </li>
 247         <li>JKISAPI_NAME - Name of the ISAPI Redirector dll without extension
 248         </li>
 249     </ul>
 250 </p>
 251 <p><div class="example"><pre>
 252 # Use the logs in the installation path of ISAPI Redirector
 253 log_file=$(ISAPI_PATH)\$(ISAPI_NAME).log
 254 </pre></div></p>
 255 </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>
 256 <p>
 257 The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the
 258 <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> program provided with Apache HTTP Server.
 259 </p>
 260 <p>
 261 To configure log rotation, configure a <b>log_file</b>, and one of the <b>log_rotationtime</b> or <b>log_filesize</b> options.
 262 If both are specified, the <b>log_rotationtime</b> will take precedence, and <b>log_filesize</b> will be ignored.
 263 <br>For example, to configure daily rotation of the log file:
 264 </p>
 265 <div class="example"><pre>
 266 # Configuration file for the Jakarta ISAPI Redirector
 267 ...
 268
 269 # Full path to the log file for the ISAPI Redirector
 270 log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log
 271
 272 # Log level (debug, info, warn, error or trace)
 273 log_level=info
 274
 275 # Rotate the log file every day
 276 log_rotationtime=86400
 277
 278 ...
 279 </pre></div>
 280 <p>
 281 Or to configure rotation of the log file when it reaches 5MB in size:
 282 </p>
 283 <div class="example"><pre>
 284 # Configuration file for the Jakarta ISAPI Redirector
 285 ...
 286
 287 # Full path to the log file for the ISAPI Redirector
 288 log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log
 289
 290 # Log level (debug, info, warn, error or trace)
 291 log_level=info
 292
 293 # Rotate the log file at 5 MB
 294 log_filesize=5M
 295
 296 ...
 297 </pre></div>
 298 <p>
 299 The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure
 300  a log file name with <b class="code">strftime(3)</b> format codes in it, then ensure it specifies the same granularity
 301  as the rotation time configured, e.g. <b>%Y-%m-%d</b> if rotating daily (<b>log_rotationtime=86400</b>).
 302 <br>See the <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> documentation for more examples.
 303 </p>
 304
 305 </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>
 306 <p>
 307 The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not
 308 as powerful as Apache Httpd's mod_rewrite, it allows a simple exchange of request URIs
 309 </p>
 310 <p>
 311 The rule is in the form original-url-prefix=forward-url-prefix. For example:
 312 </p>
 313 <div class="example"><pre>
 314 # Simple rewrite rules, making /jsp-examples
 315 # and /servlets-examples available under shorter URLs
 316 /jsp/=/jsp-examples/
 317 /servlets/=/servlets-examples/
 318 </pre></div>
 319 <p>
 320 You can also use regular expressions, if you prefix the rule with a tilde <b class="code">~</b>:
 321 </p>
 322 <div class="example"><pre>
 323 # Complex rewrite rule, adding "-examples"
 324 # to the first path component of all requests
 325 ~/([^/]*)=/$1-examples
 326 </pre></div>
 327 <p>
 328 Note that uriworkermap.properties must use the URLs before rewriting.
 329 </p>
 330 </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>
 331         Copyright &copy; 1999-2011, Apache Software Foundation
 332         </em></font></div></td></tr></table></body></html>