The Apache Tomcat Connectors - Reference Guide

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 '=':

/myapp=myworker

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:

# This is a white space example
/myapp=myworker
  /myapp=myworker
/myapp  =  myworker

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).

# 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

# Mapping the URI /myapp1 and everything under /myapp1/:
/myapp1|/*=myworker-a

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 '!':

# Mapping the URI /myapp and everything under /myapp/:
/myapp|/*=myworker
# Exclude the subdirectory static:
!/myapp/static|/*=myworker
# Exclude some suffixes:
!*.html=myworker

# 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=*

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 '-':

# We are not in maintenance.
# The maintenance rule got defined somewhere else.
-/*=maintenance

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 (for the Apache HTTP Server) 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 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:

# 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

The extension reply_timeout sets a reply timeout for a single mapping rule.

# Setting a reply_timeout of 1 minute
# only for this mapping.
/myapp=myworker;reply_timeout=60000

The extension sticky_ignore will disable session stickyness for a single mapping rule.

# Disable session stickyness
# only for this mapping.
/myapp/loginform.jsp=myworker;sticky_ignore=1

This extension is available since version 1.2.33.

The extension stateless is only useful when using session based load balancing. In this case normally any request which does not come with a session id counts as a new session. If you mark a mapping rule with the stateless extension, then the requests matching the mapping rule will not count as a new session, even if they do not come with a session id.

# Don't let static content trash our session balancing
/myapp/static/*=myworker;stateless=1

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.

# Stop forwarding only for member1 of loadbalancer
/myapp=myloadbalancer;stopped=member1

# Stop forwarding for member01 and member02 of loadbalancer
# Disable forwarding for member21 and member22 of loadbalancer
/myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22

The extension fail_on_status can be used in any rule:

# 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

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.

# 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

The extensions

• session_cookie
• session_path
• set_session_cookie
• session_cookie_path

When using the ISAPI redirector for Microsoft 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.

# 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

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

# 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

For the Apache HTTP Server 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.