diff options
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml')
| -rw-r--r-- | rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml | 422 |
1 files changed, 422 insertions, 0 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml new file mode 100644 index 00000000..f9a83dea --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml @@ -0,0 +1,422 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="uriworkermap.html"> + + &project; + + <properties> + <author email="rjung@apache.org">Rainer Jung</author> + <author email="mturk@apache.org">Mladen Turk</author> + <title>uriworkermap.properties configuration</title> + </properties> + +<body> + +<section name="Introduction"> +<br/> +<p> +The forwarding of requests from the web server to tomcat gets configured by defining mapping rules. +Such a rule maps requests to workers. The request part of the map is described by a URI pattern, +the worker by it's worker name. +</p> +<p> +The so-called <b>uriworkermap</b> file is a mechanism of defining rules, +which works for all web servers. There exist also other web server specific configuration +options for defining rules, which will be mostly discussed on the reference pages for +configuring tomcat connectors for the individual web servers. +</p> +<p> +The name of the file is usually uriworkermap.properties, +although this is configurable in the web server. +Please consult the web server specific documentation pages on +how to enable the uriworkermap file. +</p> +<p> +The main features supported by the uriworkermap file are +<ul> +<li> +Support for comments in the rule file. +</li> +<li> +Exact and wildchar matches, shortcuts to map a directory and all including content. +</li> +<li> +Exclusion rules, disabling of rules and rule priorities. +</li> +<li> +Rule extensions, modifying worker behaviour per rule. +</li> +<li> +Virtual host integration: uri mapping rules can be expressed per virtual host. +The details are web server specific though. +</li> +<li> +Dynamic reloading: The file gets checked periodically for changes. +New versions are automatically reloaded without web server restarts. +</li> +<li> +Integration with the status worker. +</li> +</ul> +The following sections describe these aspects in more detail. +</p> +</section> + +<section name="Syntax"> +<br/> +<subsection name="Line format"> +<br/> +<p> +The file has a line based format. There are no continuation characters, +so each rule needs to be defined on a single line. Each rule is a pair consisting +of a URI pattern and a worker name, combined by an equals sign '=': +<source> + /myapp=myworker +</source> +The URI pattern is case sensitive. +</p> +</subsection> +<subsection name="Comments, white space"> +<br/> +<p> +All text after and including the character '#' gets ignored and can be used for comments. +Leading and trailing white space gets trimmed around the URI pattern and also around the worker name. +The following definitions are all equivalent: +<source> + # This is a white space example + /myapp=myworker + /myapp=myworker + /myapp = myworker +</source> +</p> +</subsection> + +<subsection name="URI patterns"> +<br/> +<p> +Inside the URI pattern three special characters can be used, '*', '?' and '|'. +The character '*' is a wildchar that matches any number of arbitrary characters +in the URI, '?' matches exactly one character. +Each URI pattern has to start with the character '/', or with '*' or with '?', +optionally prefixed by any combination of the modifiers '!' and '-' (see next section). +<source> + # Mapping the URI /myapp1 and everything under /myapp1/: + /myapp1=myworker-a + /myapp1/*=myworker-a + # Mapping all URI which end with a common suffix: + *.jsp=myworker + *.do=myworker +</source> +Since the first case of mapping a certain location and everything inside +it is very common, the character '|' gives a handy shortcut: +<source> + # Mapping the URI /myapp1 and everything under /myapp1/: + /myapp1|/*=myworker-a +</source> +The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'. +</p> +</subsection> +</section> + +<section name="Exclusion, Disabling and Priorities"> +<br/> + +<subsection name="Exclusions and rule disabling"> +<br/> +<p> +Exclusion rules allows to define exclusions from URI rules, which would forward +requests to tomcat. If the exclusion rule matches, the request will not be forwarded. +This is usually used to serve static content by the web server. +A rule is an exclusion rule, if it is suffixed with '!': +<source> + # Mapping the URI /myapp and everything under /myapp/: + /myapp|/*=myworker + # Exclude the subdirectory static: + !/myapp/static|/*=myworker + # Exclude some suffixes: + !*.html=myworker +</source> +An exclusion rule overrides a normal mapping rule only, if the worker names in the +normal rule and in the exclusion rule are the same. Starting with version 1.2.26 of JK +you can apply an exclusion rule to any worker, by using the star character '*' as +the worker name in the exclusion rule. +More complex patterns in exclusion worker names are not allowed. +<source> + # Mapping the webapps /myapp1 and /myapp2: + /myapp1|/*=myworker1 + /myapp2|/*=myworker2 + # Exclude the all subdirectories static for all workers: + !/*/static|/*=* + # Exclude some suffixes for all workers: + !*.html=* +</source> +</p> +<p> +Rule disabling comes into play, if your web server merges rules from various sources, +and you want to disable any rule defined previously. Since the uriworkermap file gets +reloaded dynamically, you can use this to temporarily disable request forwarding: +A rule gets disabled, if it is suffixed with '-': +<source> + # We are not in maintenance. + # The maintenance rule got defined somewhere else. + -/*=maintenance +</source> +Exclusion rules can get disabled as well, then the rule starts with '-!'. +</p> +</subsection> + +<subsection name="Mapping priorities"> +<br/> +<p> +The most restrictive URI pattern is applied first. More precisely the URI patterns are +sorted by the number of '/' characters in the pattern (highest number first), and +rules with equal numbers are sorted by their string length (longest first). +</p> +<p> +If both distinctions still do not suffice, then the defining source of the rule is considered. +Rules defined in uriworkermap.properties come first, before rules defined by JkMount (Apache) +and inside workers.properties using the mount attribute. +</p> +<p> +All disabled rules are ignored. Exclusion rules are applied after all normal rules +have been applied. +</p> +<p> +There is no defined behaviour, for the following configuration conflict: +using literally the same URI pattern in the same defining source but with +different worker targets. +</p> +</subsection> +</section> + +<section name="Rule extensions"> +<br/> +<p> +Rule extensions were added in version 1.2.27 and are not available in earlier versions. +</p> +<subsection name="Syntax"> +<br/> +<p> +Rule extensions are additional attributes, that can be attached to any rule. +They are added at the end of the rule, each extension separated by a semicolon: +<source> + # This is an extension example, + # setting a reply_timeout of 1 minute + # only for this mapping. + /myapp=myworker;reply_timeout=60000 + # + # This is an example using multiple extensions + /myapp=myloadbalancer;reply_timeout=60000;stopped=member1 +</source> +Attributes set via rule extensions always overwrite conflicting +configurations in the worker definition file. +</p> +</subsection> +<subsection name="Extension reply_timeout"> +<br/> +<p> +The extension <code>reply_timeout</code> sets a reply timeout for a single mapping rule. +<source> + # Setting a reply_timeout of 1 minute + # only for this mapping. + /myapp=myworker;reply_timeout=60000 +</source> +It overrides any <code>reply_timeout</code> defined for the worker. The extension allows +to set a reasonable default reply timeout to the worker, and a more relaxed +reply timeout to URLs, which are known to start time intensive tasks. +For a general description of reply timeouts see the +<a href="../generic_howto/timeouts.html#Reply Timeout">timeouts</a> documentation. +</p> +</subsection> +<subsection name="Extensions active/disabled/stopped"> +<br/> +<p> +The extensions <code>active</code>, <code>disabled</code>, and <code>stopped</code> +can be used in a load balancer mapping rule to set selected members +of the load balancer into a special activation state. +<source> + # Stop forwarding only for member1 of loadbalancer + /myapp=myloadbalancer;stopped=member1 +</source> +Multiple members must be separated by commas or white space: +<source> + # Stop forwarding for member01 and member02 of loadbalancer + # Disable forwarding for member21 and member22 of loadbalancer + /myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22 +</source> +For the precise meaning of the activation states see the description of +<a href="../reference/workers.html#Advanced Worker Directives">activation</a>. +</p> +</subsection> +<subsection name="Extension fail_on_status"> +<br/> +<p> +The extension <code>fail_on_status</code> can be used in any rule: +<source> + # Send 503 instead of 404 and 500, + # and if we get a 503 also set the worker to error + /myapp=myworker;fail_on_status=-404,-500,503 +</source> +Multiple status codes must be separated by commas. +For the precise meaning of the attribute see the description of +<a href="../reference/workers.html#Advanced Worker Directives">fail_on_status</a>. +</p> +</subsection> +<subsection name="Extension use_server_errors"> +<br/> +<p> +The extension <code>use_server_errors</code> allows to let the web server +send an error page, instead of the backend (e.g. Tomcat) error page. +This is useful, if one wants to send customized error pages, but those are +not part of all web applications. They can then be put onto the web server. +</p> +<p> +The value of <code>use_server_errors</code> is a positive number. +Any request send to the backend, that returns with an http status +code bigger or equal to <code>use_server_errors</code>, will +be answered to the client with the error page of the web server +for this status code. +<source> + # Use web server error page for all errors + /myapp=myworker;use_server_errors=400 + # Use web server error page only for technical errors + /myotherapp=myworker;use_server_errors=500 +</source> +</p> +</subsection> +</section> + +<section name="Virtual host integration"> +<br/> + +<subsection name="IIS"> +<br/> +<p> +When using IIS you can restrict individual rules to special virtual hosts +by prefixing the URI pattern with the virtual host information. +The rules is that the url must be prefixed with the host name. +<source> + # Use www.foo.org as virtual host + /www.foo.org/myapp/*=myworker + # Use www.bar.org as virtual host + /www.bar.org/myapp/*=myworker + # Normal mapping + /mysecondapp/*=myworker +</source> +</p> +<p> +Note that /mysecondapp/* will be mapped to all virtual hosts present. +In case one needs to prevent the mappings to some particular virtual host then +the exclusion rule must be used +<source> + # Make sure the myapp is accessible by all virtual hosts + /myapp/*=myworker + # Disable mapping myapp for www.foo.org virtual host + !/www.foo.org/myapp/*=myworker +</source> +</p> +</subsection> + +<subsection name="Apache httpd"> +<br/> +<p> +For Apache you can define individual uriworkermap files per virtual host. +The directive JkMountFile can be used in the main server and in each virtual host. +If a virtual host does not use JkMountfile, but JkMountCopy is set to 'On', +then it inherits the JkMountFile from the main server. If you want all vhost to inherit +mounts from the main server, you can set JkMountCopy to 'All' in the main server. +</p> +</subsection> +</section> + +<section name="Dynamic reloading"> +<br/> +<p> +When a request is being processed, tomcat connectors check the file modification time +of the uriworkermap file. To keep the performance penalty low, this happens only, +if the last check happened at least n seconds ago. +</p> +<p> +For Apache you can configure the interval "n" using the directive JkMountFileReload, +for IIS you would use the attribute worker_mount_reload. +The default value is 60 seconds. A value of "0" turns off the reloading. +</p> +<p> +If the file changed, it gets reloaded completely. If there exist rules coming +from other sources than the uriworkermap file (e.g. the workers.properties mount +attribute or JkMount with Apache httpd), the new uriworkermap file gets dynamically +merged with these ones exactly like when you do a web server restart. +</p> +<p> +Until version 1.2.19 reloading behaved slightly differently: it continuously added +the full contents of the uriworkermap file to the rule mapping. The merging rules +were, that duplicated got eliminated and old rules could be disabled, by defining the +rule as disabled in the new file. Rules never got deleted. +</p> +</section> + +<section name="Status worker integration"> +<br/> +<p> +The configuration view of the status worker also shows the various mapping rules. +After each worker's configuration, the rules are listed, that forward to this worker. +The list contains four columns: +<ul> +<li> +the name of the virtual server +</li> +<li> +the URI pattern, prefixed with '-' for a disabled pattern and '!' for an exclusion pattern +</li> +<li> +the type of the rule: Exact or Wildchar +</li> +<li> +and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +</li> +</ul> +</p> +<p> +<b>Note: </b>The following restriction has been removed starting with version 1.2.26. +<br/> +For Apache httpd, there is an important subtlety: the request going to the status worker +gets executed in the context of some server (main or virtual). The status worker will only show the +mapping rules, that are defined for this server (main or virtual). +<br/> +Until version 1.2.25 the list contained three columns: +<ul> +<li> +the type of the rule: Exact or Wildchar, eventually prefixed with Disabled or Unmount (for exclusion rules) +</li> +<li> +the URI pattern +</li> +<li> +and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +</li> +</ul> +</p> +</section> + +</body> +</document> |