]>
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 '=': The URI pattern is case sensitive.
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). Since the first case of mapping a certain location and everything inside it is very common, the character '|' gives a handy shortcut: The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'.
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 '!': 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.
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 '-': Exclusion rules can get disabled as well, then the rule starts 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: Attributes set via rule extensions always overwrite conflicting configurations in the worker definition file.
The extension reply_timeout
sets a reply timeout for a single mapping rule.
It overrides any 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.
Multiple members must be separated by commas or white space:
For the precise meaning of the activation states see the description of
activation.
The extension fail_on_status
can be used in any rule:
Multiple status codes must be separated by commas.
For the precise meaning of the attribute see the description of
fail_on_status.
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: