Apache Tomcat Development

The rewrite Valve

Introduction

The rewrite valve implements URL rewrite functionality in a way that is
very similar to mod_rewrite from Apache HTTP Server.

Configuration

The rewrite valve is configured as a valve using the org.apache.catalina.valves.rewrite.RewriteValve
class name.

The rewrite valve can be configured as a valve added in a Host.
See virtual-server documentation for
informations how to configure it. It will use a rewrite.config file
containing the rewrite directives, it must be placed in the Host configuration
folder.

It can also be in the context.xml of a webapp.
The valve will then use a rewrite.config file containing the
rewrite directives, it must be placed in the WEB-INF folder of the web application

Directives

The rewrite.config file contains a list of directives which closely resemble
the directives used by mod_rewrite, in particular the central RewriteRule and
RewriteCond directives.

Note: This section is a modified version of the mod_rewrite documentation,
which is Copyright 1995-2006 The Apache Software Foundation, and licensed under the
under the Apache License, Version 2.0.

RewriteCond

Syntax: RewriteCond TestString CondPattern

The RewriteCond directive defines a rule condition. One or more RewriteCond
can precede a RewriteRule directive. The following rule is then only used if both
the current state of the URI matches its pattern, and if these conditions are met.

TestString is a string which can contain the
following expanded constructs in addition to plain text:

RewriteRule backreferences: These are
backreferences of the form $N
(0 <= N <= 9), which provide access to the grouped
parts (in parentheses) of the pattern, from the
RewriteRule which is subject to the current
set of RewriteCond conditions..

RewriteCond backreferences: These are
backreferences of the form %N
(1 <= N <= 9), which provide access to the grouped
parts (again, in parentheses) of the pattern, from the last matched
RewriteCond in the current set
of conditions.

These variables all
correspond to the similarly named HTTP
MIME-headers and Servlet API methods.
Most are documented elsewhere in the Manual or in
the CGI specification. Those that are special to
the rewrite valve include those below.

REQUEST_PATH

Corresponds to the full path that is used for mapping.

CONTEXT_PATH

Corresponds to the path of the mapped context.

SERVLET_PATH

Corresponds to the servlet path.

THE_REQUEST

The full HTTP request line sent by the
browser to the server (e.g., "GET
/index.html HTTP/1.1"). This does not
include any additional headers sent by the
browser.

REQUEST_URI

The resource requested in the HTTP request
line. (In the example above, this would be
"/index.html".)

REQUEST_FILENAME

The full local file system path to the file or
script matching the request.

HTTPS

Will contain the text "on" if the connection is
using SSL/TLS, or "off" otherwise.

Other things you should be aware of:

The variables SCRIPT_FILENAME and REQUEST_FILENAME
contain the same value - the value of the
filename field of the internal
request_rec structure of the Apache server.
The first name is the commonly known CGI variable name
while the second is the appropriate counterpart of
REQUEST_URI (which contains the value of the
uri field of request_rec).

%{ENV:variable}, where variable can be
any Java system property, is also available.

%{SSL:variable}, where variable is the
name of an SSL environment
variable, are not implemented yet. Example:
%{SSL:SSL_CIPHER_USEKEYSIZE} may expand to
128.

%{HTTP:header}, where header can be
any HTTP MIME-header name, can always be used to obtain the
value of a header sent in the HTTP request.
Example: %{HTTP:Proxy-Connection} is
the value of the HTTP header
``Proxy-Connection:''.

CondPattern is the condition pattern,
a regular expression which is applied to the
current instance of the TestString.
TestString is first evaluated, before being matched against
CondPattern.

Remember:CondPattern is a
perl compatible regular expression with some
additions:

You can prefix the pattern string with a
'!' character (exclamation mark) to specify a
non-matching pattern.

There are some special variants of CondPatterns.
Instead of real regular expression strings you can also
use one of the following:

'<CondPattern' (lexicographically
precedes)
Treats the CondPattern as a plain string and
compares it lexicographically to TestString. True if
TestString lexicographically precedes
CondPattern.

'>CondPattern' (lexicographically
follows)
Treats the CondPattern as a plain string and
compares it lexicographically to TestString. True if
TestString lexicographically follows
CondPattern.

'=CondPattern' (lexicographically
equal)
Treats the CondPattern as a plain string and
compares it lexicographically to TestString. True if
TestString is lexicographically equal to
CondPattern (the two strings are exactly
equal, character for character). If CondPattern
is "" (two quotation marks) this
compares TestString to the empty string.

'-d' (is
directory)
Treats the TestString as a pathname and tests
whether or not it exists, and is a directory.

'-f' (is regular
file)
Treats the TestString as a pathname and tests
whether or not it exists, and is a regular file.

'-s' (is regular file, with
size)
Treats the TestString as a pathname and tests
whether or not it exists, and is a regular file with size greater
than zero.

Note:
All of these tests can
also be prefixed by an exclamation mark ('!') to
negate their meaning.

You can also set special flags for
CondPattern by appending
[flags]
as the third argument to the RewriteCond
directive, where flags is a comma-separated list of any of the
following flags:

'nocase|NC'
(no case)
This makes the test case-insensitive - differences
between 'A-Z' and 'a-z' are ignored, both in the
expanded TestString and the CondPattern.
This flag is effective only for comparisons between
TestString and CondPattern. It has no
effect on file system and subrequest checks.

'ornext|OR'
(or next condition)
Use this to combine rule conditions with a local OR
instead of the implicit AND. Typical example:

Explanation: If you use a browser which identifies itself
as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
get the max homepage (which could include frames, or other special
features).
If you use the Lynx browser (which is terminal-based), then
you get the min homepage (which could be a version designed for
easy, text-only browsing).
If neither of these conditions apply (you use any other browser,
or your browser identifies itself as something non-standard), you get
the std (standard) homepage.

RewriteMap

Syntax: RewriteMap name rewriteMapClassName optionalParameters

The maps are implemented using an interface that users must implement. Its class
name is org.apache.catalina.valves.rewrite.RewriteMap, and its code is:

RewriteRule

Syntax: RewriteRule Pattern Substitution

The RewriteRule directive is the real
rewriting workhorse. The directive can occur more than once,
with each instance defining a single rewrite rule. The
order in which these rules are defined is important - this is the order
in which they will be applied at run-time.

Pattern is a perl compatible regular
expression, which is applied to the current URL.
``Current'' means the value of the URL when this rule is
applied. This may not be the originally requested URL,
which may already have matched a previous rule, and have been
altered.

Some hints on the syntax of regular
expressions:

Text:. Any single character
[chars] Character class: Any character of the class ``chars''
[^chars] Character class: Not a character of the class ``chars''
text1|text2 Alternative: text1 or text2
Quantifiers:? 0 or 1 occurrences of the preceding text
* 0 or N occurrences of the preceding text (N > 0)
+ 1 or N occurrences of the preceding text (N > 1)
Grouping:(text) Grouping of text
(used either to set the borders of an alternative as above, or
to make backreferences, where the Nth group can
be referred to on the RHS of a RewriteRule as $N)
Anchors:^ Start-of-line anchor
$ End-of-line anchor
Escaping:\char escape the given char
(for instance, to specify the chars ".[]()" etc.)

For more information about regular expressions, have a look at the
perl regular expression manpage ("perldoc
perlre"). If you are interested in more detailed
information about regular expressions and their variants
(POSIX regex etc.) the following book is dedicated to this topic:

In the rules, the NOT character
('!') is also available as a possible pattern
prefix. This enables you to negate a pattern; to say, for instance:
``if the current URL does NOT match this
pattern''. This can be used for exceptional cases, where
it is easier to match the negative pattern, or as a last
default rule.

Note: When using the NOT character to negate a pattern, you cannot include
grouped wildcard parts in that pattern. This is because, when the
pattern does NOT match (i.e., the negation matches), there are no
contents for the groups. Thus, if negated patterns are used, you
cannot use $N in the substitution string!

The substitution of a
rewrite rule is the string which is substituted for (or
replaces) the original URL which Pattern
matched. In addition to plain text, it can include

Back-references are identifiers of the form
$N
(N=0..9), which will be replaced
by the contents of the Nth group of the
matched Pattern. The server-variables are the same
as for the TestString of a RewriteCond
directive. The mapping-functions come from the
RewriteMap directive and are explained there.
These three types of variables are expanded in the order above.

As already mentioned, all rewrite rules are
applied to the Substitution (in the order in which
they are defined
in the config file). The URL is completely
replaced by the Substitution and the
rewriting process continues until all rules have been applied,
or it is explicitly terminated by a
L flag.

The special characters $ and % can
be quoted by prepending them with a backslash character
\.

There is a special substitution string named
'-' which means: NO
substitution! This is useful in providing
rewriting rules which only match
URLs but do not substitute anything for them. It is commonly used
in conjunction with the C (chain) flag, in order
to apply more than one pattern before substitution occurs.

Unlike newer mod_rewrite versions, the Tomcat rewrite valve does
not automatically support absolute URLs (the specific redirect flag
must be used to be able to specify an absolute URLs, see below)
or direct file serving.

Additionally you can set special flags for Substitution by
appending [flags]
as the third argument to the RewriteRule
directive. Flags is a comma-separated list of any of the
following flags:

'chain|C'
(chained with next rule)
This flag chains the current rule with the next rule
(which itself can be chained with the following rule,
and so on). This has the following effect: if a rule
matches, then processing continues as usual -
the flag has no effect. If the rule does
not match, then all following chained
rules are skipped. For instance, it can be used to remove the
``.www'' part, inside a per-directory rule set,
when you let an external redirect happen (where the
``.www'' part should not occur!).

'cookie|CO=NAME:VAL:domain[:lifetime[:path]]'
(set cookie)
This sets a cookie in the client's browser. The cookie's name
is specified by NAME and the value is
VAL. The domain field is the domain of the
cookie, such as '.apache.org', the optional lifetime
is the lifetime of the cookie in minutes, and the optional
path is the path of the cookie

'env|E=VAR:VAL'
(set environment variable)
This forces a request attribute named VAR to
be set to the value VAL, where VAL can
contain regexp backreferences ($N and
%N) which will be expanded. You can use this
flag more than once, to set more than one variable.

'forbidden|F' (force URL
to be forbidden)
This forces the current URL to be forbidden - it immediately
sends back a HTTP response of 403 (FORBIDDEN).
Use this flag in conjunction with
appropriate RewriteConds to conditionally block some
URLs.

'gone|G' (force URL to be
gone)
This forces the current URL to be gone - it
immediately sends back a HTTP response of 410 (GONE). Use
this flag to mark pages which no longer exist as gone.

'host|H=Host'
(apply rewriting to host)
Rather that rewrite the URL, the virtual host will be
rewritten.

'last|L'
(last rule)
Stop the rewriting process here and don't apply any more
rewrite rules. This corresponds to the Perl
last command or the break command
in C. Use this flag to prevent the currently
rewritten URL from being rewritten further by following
rules. For example, use it to rewrite the root-path URL
('/') to a real one, e.g.,
'/e/www/'.

'next|N'
(next round)
Re-run the rewriting process (starting again with the
first rewriting rule). This time, the URL to match is no longer
the original URL, but rather the URL returned by the last rewriting rule.
This corresponds to the Perl next command or
the continue command in C. Use
this flag to restart the rewriting process -
to immediately go to the top of the loop.Be careful not to create an infinite
loop!

'nocase|NC'
(no case)
This makes the Pattern case-insensitive,
ignoring difference between 'A-Z' and
'a-z' when Pattern is matched against the current
URL.

'noescape|NE'
(no URI escaping of
output)
This flag prevents the rewrite valve from applying the usual URI
escaping rules to the result of a rewrite. Ordinarily,
special characters (such as '%', '$', ';', and so on)
will be escaped into their hexcode equivalents ('%25',
'%24', and '%3B', respectively); this flag prevents this
from happening. This allows percent symbols to appear in
the output, as in

RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

which would turn '/foo/zed' into a safe
request for '/bar?arg=P1=zed'.

'qsappend|QSA'
(query string
append)
This flag forces the rewrite engine to append a query
string part of the substitution string to the existing string,
instead of replacing it. Use this when you want to add more
data to the query string via a rewrite rule.

'redirect|R
[=code]' (force redirect)
Prefix Substitution with
http://thishost[:thisport]/ (which makes the
new URL a URI) to force a external redirection. If no
code is given, a HTTP response of 302 (MOVED
TEMPORARILY) will be returned. If you want to use other response
codes in the range 300-400, simply specify the appropriate number
or use one of the following symbolic names:
temp (default), permanent,
seeother. Use this for rules to
canonicalize the URL and return it to the client - to
translate ``/~'' into
``/u/'', or to always append a slash to
/u/user, etc.Note: When you use this flag, make
sure that the substitution field is a valid URL! Otherwise,
you will be redirecting to an invalid location. Remember
that this flag on its own will only prepend
http://thishost[:thisport]/ to the URL, and rewriting
will continue. Usually, you will want to stop rewriting at this point,
and redirect immediately. To stop rewriting, you should add
the 'L' flag.

'skip|S=num'
(skip next rule(s))
This flag forces the rewriting engine to skip the next
num rules in sequence, if the current rule
matches. Use this to make pseudo if-then-else constructs:
The last rule of the then-clause becomes
skip=N, where N is the number of rules in the
else-clause. (This is not the same as the
'chain|C' flag!)

'type|T=MIME-type'
(force MIME type)
Force the MIME-type of the target file to be
MIME-type. This can be used to
set up the content-type based on some conditions.
For example, the following snippet allows .php files to
be displayed by mod_php if they are called with
the .phps extension: