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