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