From 9401f816dd0d9d550fe98a8507224bde51c4b847 Mon Sep 17 00:00:00 2001
From: hongbotian
+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.
+
+The so-called uriworkermap 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.
+
+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.
+
+The main features supported by the uriworkermap file are
+
+
+
+The following sections describe these aspects in more detail.
+
+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 '=':
+
+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:
+
+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).
+
+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 '!':
+
+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 '-':
+
+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). +
++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. +
++All disabled rules are ignored. Exclusion rules are applied after all normal rules +have been applied. +
++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. +
++Rule extensions were added in version 1.2.27 and are not available in earlier versions. +
+
+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:
+
+The extension reply_timeout
sets a reply timeout for a single mapping rule.
+reply_timeout
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
+timeouts documentation.
+
+The extensions active
, disabled
, and stopped
+can be used in a load balancer mapping rule to set selected members
+of the load balancer into a special activation state.
+
+The extension fail_on_status
can be used in any rule:
+
+The extension use_server_errors
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.
+
+The value of use_server_errors
is a positive number.
+Any request send to the backend, that returns with an http status
+code bigger or equal to use_server_errors
, will
+be answered to the client with the error page of the web server
+for this status code.
+
+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.
+
+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
+
+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. +
++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. +
++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. +
++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. +
++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. +
++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: +
+Note: The following restriction has been removed starting with version 1.2.26.
+
+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).
+
+Until version 1.2.25 the list contained three columns:
+