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

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Reference Guide - uriworkermap.properties configuration</title><meta name="author" value="Rainer Jung"><meta name="email" value="rjung@apache.org"><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>uriworkermap.properties configuration</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="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
   2 <br>
   3 <p>
   4 The forwarding of requests from the web server to tomcat gets configured by defining mapping rules.
   5 Such a rule maps requests to workers. The request part of the map is described by a URI pattern,
   6 the worker by it's worker name.
   7 </p>
   8 <p>
   9 The so-called <b>uriworkermap</b> file is a mechanism of defining rules,
  10 which works for all web servers. There exist also other web server specific configuration
  11 options for defining rules, which will be mostly discussed on the reference pages for
  12 configuring tomcat connectors for the individual web servers.
  13 </p>
  14 <p>
  15 The name of the file is usually uriworkermap.properties,
  16 although this is configurable in the web server.
  17 Please consult the web server specific documentation pages on
  18 how to enable the uriworkermap file.
  19 </p>
  20 <p>
  21 The main features supported by the uriworkermap file are
  22 <ul>
  23 <li>
  24 Support for comments in the rule file.
  25 </li>
  26 <li>
  27 Exact and wildchar matches, shortcuts to map a directory and all including content.
  28 </li>
  29 <li>
  30 Exclusion rules, disabling of rules and rule priorities.
  31 </li>
  32 <li>
  33 Rule extensions, modifying worker behaviour per rule.
  34 </li>
  35 <li>
  36 Virtual host integration: uri mapping rules can be expressed per virtual host.
  37 The details are web server specific though.
  38 </li>
  39 <li>
  40 Dynamic reloading: The file gets checked periodically for changes.
  41 New versions are automatically reloaded without web server restarts.
  42 </li>
  43 <li>
  44 Integration with the status worker.
  45 </li>
  46 </ul>
  47 The following sections describe these aspects in more detail.
  48 </p>
  49 </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="Syntax"><strong>Syntax</strong></a></font></td></tr><tr><td><blockquote>
  50 <br>
  51 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Line format"><strong>Line format</strong></a></font></td></tr><tr><td><blockquote>
  52 <br>
  53 <p>
  54 The file has a line based format. There are no continuation characters,
  55 so each rule needs to be defined on a single line. Each rule is a pair consisting
  56 of a URI pattern and a worker name, combined by an equals sign '=':
  57 <div class="example"><pre>
  58   /myapp=myworker
  59 </pre></div>
  60 The URI pattern is case sensitive.
  61 </p>
  62 </blockquote></td></tr></table>
  63 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Comments, white space"><strong>Comments, white space</strong></a></font></td></tr><tr><td><blockquote>
  64 <br>
  65 <p>
  66 All text after and including the character '#' gets ignored and can be used for comments.
  67 Leading and trailing white space gets trimmed around the URI pattern and also around the worker name.
  68 The following definitions are all equivalent:
  69 <div class="example"><pre>
  70   # This is a white space example
  71   /myapp=myworker
  72      /myapp=myworker
  73   /myapp  =  myworker
  74 </pre></div>
  75 </p>
  76 </blockquote></td></tr></table>
  77
  78 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="URI patterns"><strong>URI patterns</strong></a></font></td></tr><tr><td><blockquote>
  79 <br>
  80 <p>
  81 Inside the URI pattern three special characters can be used, '*', '?' and '|'.
  82 The character '*' is a wildchar that matches any number of arbitrary characters
  83 in the URI, '?' matches exactly one character.
  84 Each URI pattern has to start with the character '/', or with '*' or with '?',
  85 optionally prefixed by any combination of the modifiers '!' and '-' (see next section).
  86 <div class="example"><pre>
  87   # Mapping the URI /myapp1 and everything under /myapp1/:
  88   /myapp1=myworker-a
  89   /myapp1/*=myworker-a
  90   # Mapping all URI which end with a common suffix:
  91   *.jsp=myworker
  92   *.do=myworker
  93 </pre></div>
  94 Since the first case of mapping a certain location and everything inside
  95 it is very common, the character '|' gives a handy shortcut:
  96 <div class="example"><pre>
  97   # Mapping the URI /myapp1 and everything under /myapp1/:
  98   /myapp1|/*=myworker-a
  99 </pre></div>
 100 The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'.
 101 </p>
 102 </blockquote></td></tr></table>
 103 </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="Exclusion, Disabling and Priorities"><strong>Exclusion, Disabling and Priorities</strong></a></font></td></tr><tr><td><blockquote>
 104 <br>
 105
 106 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Exclusions and rule disabling"><strong>Exclusions and rule disabling</strong></a></font></td></tr><tr><td><blockquote>
 107 <br>
 108 <p>
 109 Exclusion rules allows to define exclusions from URI rules, which would forward
 110 requests to tomcat. If the exclusion rule matches, the request will not be forwarded.
 111 This is usually used to serve static content by the web server.
 112 A rule is an exclusion rule, if it is suffixed with '!':
 113 <div class="example"><pre>
 114   # Mapping the URI /myapp and everything under /myapp/:
 115   /myapp|/*=myworker
 116   # Exclude the subdirectory static:
 117   !/myapp/static|/*=myworker
 118   # Exclude some suffixes:
 119   !*.html=myworker
 120 </pre></div>
 121 An exclusion rule overrides a normal mapping rule only, if the worker names in the
 122 normal rule and in the exclusion rule are the same. Starting with version 1.2.26 of JK
 123 you can apply an exclusion rule to any worker, by using the star character '*' as
 124 the worker name in the exclusion rule.
 125 More complex patterns in exclusion worker names are not allowed.
 126 <div class="example"><pre>
 127   # Mapping the webapps /myapp1 and /myapp2:
 128   /myapp1|/*=myworker1
 129   /myapp2|/*=myworker2
 130   # Exclude the all subdirectories static for all workers:
 131   !/*/static|/*=*
 132   # Exclude some suffixes for all workers:
 133   !*.html=*
 134 </pre></div>
 135 </p>
 136 <p>
 137 Rule disabling comes into play, if your web server merges rules from various sources,
 138 and you want to disable any rule defined previously. Since the uriworkermap file gets
 139 reloaded dynamically, you can use this to temporarily disable request forwarding:
 140 A rule gets disabled, if it is suffixed with '-':
 141 <div class="example"><pre>
 142   # We are not in maintenance.
 143   # The maintenance rule got defined somewhere else.
 144   -/*=maintenance
 145 </pre></div>
 146 Exclusion rules can get disabled as well, then the rule starts with '-!'.
 147 </p>
 148 </blockquote></td></tr></table>
 149
 150 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Mapping priorities"><strong>Mapping priorities</strong></a></font></td></tr><tr><td><blockquote>
 151 <br>
 152 <p>
 153 The most restrictive URI pattern is applied first. More precisely the URI patterns are
 154 sorted by the number of '/' characters in the pattern (highest number first), and
 155 rules with equal numbers are sorted by their string length (longest first).
 156 </p>
 157 <p>
 158 If both distinctions still do not suffice, then the defining source of the rule is considered.
 159 Rules defined in uriworkermap.properties come first, before rules defined by JkMount (Apache)
 160 and inside workers.properties using the mount attribute.
 161 </p>
 162 <p>
 163 All disabled rules are ignored. Exclusion rules are applied after all normal rules
 164 have been applied.
 165 </p>
 166 <p>
 167 There is no defined behaviour, for the following configuration conflict:
 168 using literally the same URI pattern in the same defining source but with
 169 different worker targets.
 170 </p>
 171 </blockquote></td></tr></table>
 172 </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="Rule extensions"><strong>Rule extensions</strong></a></font></td></tr><tr><td><blockquote>
 173 <br>
 174 <p>
 175 Rule extensions were added in version 1.2.27 and are not available in earlier versions.
 176 </p>
 177 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Syntax"><strong>Syntax</strong></a></font></td></tr><tr><td><blockquote>
 178 <br>
 179 <p>
 180 Rule extensions are additional attributes, that can be attached to any rule.
 181 They are added at the end of the rule, each extension separated by a semicolon:
 182 <div class="example"><pre>
 183   # This is an extension example,
 184   # setting a reply_timeout of 1 minute
 185   # only for this mapping.
 186   /myapp=myworker;reply_timeout=60000
 187   #
 188   # This is an example using multiple extensions
 189   /myapp=myloadbalancer;reply_timeout=60000;stopped=member1
 190 </pre></div>
 191 Attributes set via rule extensions always overwrite conflicting
 192 configurations in the worker definition file.
 193 </p>
 194 </blockquote></td></tr></table>
 195 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Extension reply_timeout"><strong>Extension reply_timeout</strong></a></font></td></tr><tr><td><blockquote>
 196 <br>
 197 <p>
 198 The extension <b class="code">reply_timeout</b> sets a reply timeout for a single mapping rule.
 199 <div class="example"><pre>
 200   # Setting a reply_timeout of 1 minute
 201   # only for this mapping.
 202   /myapp=myworker;reply_timeout=60000
 203 </pre></div>
 204 It overrides any <b class="code">reply_timeout</b> defined for the worker. The extension allows
 205 to set a reasonable default reply timeout to the worker, and a more relaxed
 206 reply timeout to URLs, which are known to start time intensive tasks.
 207 For a general description of reply timeouts see the
 208 <a href="../../generic_howto/timeouts.html#Reply Timeout">timeouts</a> documentation.
 209 </p>
 210 </blockquote></td></tr></table>
 211 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Extensions active/disabled/stopped"><strong>Extensions active/disabled/stopped</strong></a></font></td></tr><tr><td><blockquote>
 212 <br>
 213 <p>
 214 The extensions <b class="code">active</b>, <b class="code">disabled</b>, and <b class="code">stopped</b>
 215 can be used in a load balancer mapping rule to set selected members
 216 of the load balancer into a special activation state.
 217 <div class="example"><pre>
 218   # Stop forwarding only for member1 of loadbalancer
 219   /myapp=myloadbalancer;stopped=member1
 220 </pre></div>
 221 Multiple members must be separated by commas or white space:
 222 <div class="example"><pre>
 223   # Stop forwarding for member01 and member02 of loadbalancer
 224   # Disable forwarding for member21 and member22 of loadbalancer
 225   /myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22
 226 </pre></div>
 227 For the precise meaning of the activation states see the description of
 228 <a href="../../reference/workers.html#Advanced Worker Directives">activation</a>.
 229 </p>
 230 </blockquote></td></tr></table>
 231 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Extension fail_on_status"><strong>Extension fail_on_status</strong></a></font></td></tr><tr><td><blockquote>
 232 <br>
 233 <p>
 234 The extension <b class="code">fail_on_status</b> can be used in any rule:
 235 <div class="example"><pre>
 236   # Send 503 instead of 404 and 500,
 237   # and if we get a 503 also set the worker to error
 238   /myapp=myworker;fail_on_status=-404,-500,503
 239 </pre></div>
 240 Multiple status codes must be separated by commas.
 241 For the precise meaning of the attribute see the description of
 242 <a href="../../reference/workers.html#Advanced Worker Directives">fail_on_status</a>.
 243 </p>
 244 </blockquote></td></tr></table>
 245 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Extension use_server_errors"><strong>Extension use_server_errors</strong></a></font></td></tr><tr><td><blockquote>
 246 <br>
 247 <p>
 248 The extension <b class="code">use_server_errors</b> allows to let the web server
 249 send an error page, instead of the backend (e.g. Tomcat) error page.
 250 This is useful, if one wants to send customized error pages, but those are
 251 not part of all web applications. They can then be put onto the web server.
 252 </p>
 253 <p>
 254 The value of <b class="code">use_server_errors</b> is a positive number.
 255 Any request send to the backend, that returns with an http status
 256 code bigger or equal to <b class="code">use_server_errors</b>, will
 257 be answered to the client with the error page of the web server
 258 for this status code.
 259 <div class="example"><pre>
 260   # Use web server error page for all errors
 261   /myapp=myworker;use_server_errors=400
 262   # Use web server error page only for technical errors
 263   /myotherapp=myworker;use_server_errors=500
 264 </pre></div>
 265 </p>
 266 </blockquote></td></tr></table>
 267 </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="Virtual host integration"><strong>Virtual host integration</strong></a></font></td></tr><tr><td><blockquote>
 268 <br>
 269
 270 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="IIS"><strong>IIS</strong></a></font></td></tr><tr><td><blockquote>
 271 <br>
 272 <p>
 273 When using IIS you can restrict individual rules to special virtual hosts
 274 by prefixing the URI pattern with the virtual host information.
 275 The rules is that the url must be prefixed with the host name.
 276 <div class="example"><pre>
 277   # Use www.foo.org as virtual host
 278   /www.foo.org/myapp/*=myworker
 279   # Use www.bar.org as virtual host
 280   /www.bar.org/myapp/*=myworker
 281   # Normal mapping
 282   /mysecondapp/*=myworker
 283 </pre></div>
 284 </p>
 285 <p>
 286 Note that /mysecondapp/* will be mapped to all virtual hosts present.
 287 In  case one needs to prevent the mappings to some particular virtual host then
 288 the exclusion rule must be used
 289 <div class="example"><pre>
 290   # Make sure the myapp is accessible by all virtual hosts
 291   /myapp/*=myworker
 292   # Disable mapping myapp for www.foo.org virtual host
 293   !/www.foo.org/myapp/*=myworker
 294 </pre></div>
 295 </p>
 296 </blockquote></td></tr></table>
 297
 298 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Apache httpd"><strong>Apache httpd</strong></a></font></td></tr><tr><td><blockquote>
 299 <br>
 300 <p>
 301 For Apache you can define individual uriworkermap files per virtual host.
 302 The directive JkMountFile can be used in the main server and in each virtual host.
 303 If a virtual host does not use JkMountfile, but JkMountCopy is set to 'On',
 304 then it inherits the JkMountFile from the main server. If you want all vhost to inherit
 305 mounts from the main server, you can set JkMountCopy to 'All' in the main server.
 306 </p>
 307 </blockquote></td></tr></table>
 308 </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="Dynamic reloading"><strong>Dynamic reloading</strong></a></font></td></tr><tr><td><blockquote>
 309 <br>
 310 <p>
 311 When a request is being processed, tomcat connectors check the file modification time
 312 of the uriworkermap file. To keep the performance penalty low, this happens only,
 313 if the last check happened at least n seconds ago.
 314 </p>
 315 <p>
 316 For Apache you can configure the interval "n" using the directive JkMountFileReload,
 317 for IIS you would use the attribute worker_mount_reload.
 318 The default value is 60 seconds. A value of "0" turns off the reloading.
 319 </p>
 320 <p>
 321 If the file changed, it gets reloaded completely. If there exist rules coming
 322 from other sources than the uriworkermap file (e.g. the workers.properties mount
 323 attribute or JkMount with Apache httpd), the new uriworkermap file gets dynamically
 324 merged with these ones exactly like when you do a web server restart.
 325 </p>
 326 <p>
 327 Until version 1.2.19 reloading behaved slightly differently: it continuously added
 328 the full contents of the uriworkermap file to the rule mapping. The merging rules
 329 were, that duplicated got eliminated and old rules could be disabled, by defining the
 330 rule as disabled in the new file. Rules never got deleted.
 331 </p>
 332 </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="Status worker integration"><strong>Status worker integration</strong></a></font></td></tr><tr><td><blockquote>
 333 <br>
 334 <p>
 335 The configuration view of the status worker also shows the various mapping rules.
 336 After each worker's configuration, the rules are listed, that forward to this worker.
 337 The list contains four columns:
 338 <ul>
 339 <li>
 340 the name of the virtual server
 341 </li>
 342 <li>
 343 the URI pattern, prefixed with '-' for a disabled pattern and '!' for an exclusion pattern
 344 </li>
 345 <li>
 346 the type of the rule: Exact or Wildchar
 347 </li>
 348 <li>
 349 and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute),
 350 'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file.
 351 </li>
 352 </ul>
 353 </p>
 354 <p>
 355 <b>Note: </b>The following restriction has been removed starting with version 1.2.26.
 356 <br>
 357 For Apache httpd, there is an important subtlety: the request going to the status worker
 358 gets executed in the context of some server (main or virtual). The status worker will only show the
 359 mapping rules, that are defined for this server (main or virtual).
 360 <br>
 361 Until version 1.2.25 the list contained three columns:
 362 <ul>
 363 <li>
 364 the type of the rule: Exact or Wildchar, eventually prefixed with Disabled or Unmount (for exclusion rules)
 365 </li>
 366 <li>
 367 the URI pattern
 368 </li>
 369 <li>
 370 and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute),
 371 'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file.
 372 </li>
 373 </ul>
 374 </p>
 375 </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>
 376         Copyright &copy; 1999-2011, Apache Software Foundation
 377         </em></font></div></td></tr></table></body></html>