<document>
<localtoc/> <parents>when, unless</parents>

Contains one or more conditions and evaluates to true if all of the contained conditions evaluate to true, false if any of the contained conditions does not evaluate to true.

<parents>when, unless</parents>

Evaluates to true if the authorization mechanism used in the request is the given value. The comparison is always case insensitive.

If the auth-type is not "none", or if the auth-type of the request is not "none", a `Cache-Control` header containing "`private`" is added to the response.

auth-type BASIC, CLIENT-CERT, DIGEST, FORM, or NONE required
send-vary Send a `Vary` header containing "`Cookie`" as part of the response true
<parents>when, unless</parents>

Evaluates to true if the value of a cookie with a given matches a regular expression , false if it does not or if the cookie does not exist.

The header of the response is updated to include "Cookie", which indicates to the browser and any intervening proxy cache that the response varies based on the submitted value of cookies.

cookie Name of the cookie required
regexp The regular expression to match optional
send-vary Send a `Vary` header containing "`Cookie`" as part of the response true

Cron syntax for specifying a time or times that that the rule should be disabled. In conjunction, enable-at and disable-at provide a means for scheduling the enablement of a rule.

<parents>rewrite-dispatch, match</parents>

If <dispatch> matches the current URL, the rest of the items in the enclosing rewrite-dispatch are not considered and the request passes immediately to normal servlet evaluation. <dispatch> is often used to specify URLs which should be handled normally before a more general pattern which modifies the URL.

For example, the following pattern uses <dispatch> to handle images and *.php files normally, but forward's all other requests to /index.php.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <dispatch regexp="\.(php|gif|css|jpg|png)"/> <forward regexp="^" target="/index.php"/> </rewrite-dispatch> </web-app>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional

Cron syntax for specifying a time or times that that the rule should be enabled, see <disable-at/>.

Set's the initial state of the rule, default is true. In conjunction with name, an initial enabled value of "false" is valuable for rules which are to be turned on and turned off at runtime.

<parents>rewrite-dispatch, match</parents>

<forbidden> sents a 403 forbidden message to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <forbidden regexp="^/protected"/> </rewrite-dispatch> </web-app>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>rewrite-dispatch, match</parents>

<forward> rewrites the current URL, forwarding it to the target using the servlet forward() call. Because <forward> is internal, it will have better performance than a <redirect> when the target URL is on the same server, the browser will not know that the underlying resource has moved.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <forward regexp="^/old" target="/new"/> </rewrite-dispatch> </web-app>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
target The target of the the foreward required
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>when, unless</parents>

Evaluates to true if the value of a header with a given matches a regular expression , false if it does not or if the header does not exist.

The header of the response is updated to include the header name which indicates to the browser and any intervening proxy cache that the response varies based on the submitted value of the header.

header Name of the header required
regexp The regular expression to match optional
send-vary Send a `Vary` header containing the header name as part of the response true
<parents>rewrite-dispatch, match</parents>

<gone> sents a 410 gone response to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <gone regexp="^/protected"/> </rewrite-dispatch> </web-app>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>rewrite-dispatch, match</parents>

<import> loads rules from an external xml file.

<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <rewrite-dispatch> <import path='/WEB-INF/rewrite-maintenance.xml' enabled="false"/> <import path='/WEB-INF/rewrite-rules.xml'/> </rewrite-dispatch> </web-app> <rewrite-dispatch xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <dispatch regexp="\.(css|gif|jpg|pdf|png)"/> <forward regexp=".*" target="/maintenance.html"/> </rewrite-dispatch>

Changes to the external file are checked for at a frequency determined by dependency-check-interval or when the `update()` operation of the mbean is invoked. If an error occurs when loading the modified file, the contents of the old file are used until the errors are corrected or the server is restarted. The log file will contain details for the error, and the `RedeployError` property of the mbean wil contain a description of the error.

Each <import> registers an mbean of type RewriteImport, with a full a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule" and an interface of . It provides the `update()`, `start()` and `stop()` operations. The `update()` operations forces an immediate check for modifications to the external file.

disable-at A cron syntax time specification for triggering disablement of the rule none
dependency-check-interval The frequency with which to check the external file for changes The dependency-check-interval of the environment
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteImport the value of
optional If false, do not require that the path exists true
path A path to an external xml file required
<parents>rewrite-dispatch, match</parents>

<load-balance> forwards requests from a <g>web-tier</g> server to a cluster of <g>app-tier</g> servers for load-balancing. Load balancing provides scalability by splitting load among many application servers and increases reliability by avoiding servers which are upgrading or restarting.

In the following example, the web-tier load-balances all traffic to a cluster of backend application servers. Because the web-tier has a proxy cache, static pages and cached pages will be served directory from the web-tier.

<load-balance> requires Resin Professional.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server id="app-a" address="192.168.3.1"> <server id="app-b" address="192.168.3.2"> ... </cluster> <cluster id="web-tier"> <server id="web-a" address="192.168.2.1"> <http port="80"/> </server> <cache/> <host id=""> <web-app id="/"> <rewrite-dispatch> <load-balance regexp="" cluster="app-tier"/> </rewrite-dispatch> </web-app> </host> </resin>
cluster The cluster that gets the matching requests required
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
sticky-sessions Whether or not sessions should be sticky true
strategy The load balancing strategy, `round-robin' or `least-connection' least-connection
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>when, unless</parents>

Evaluates to true if the value of the Locale matches a regular expression, false if it does not. The comparison is always case insensitive.

The Locale is a normalization of the value of the Accept-Language header. For example "fr" remains "fr" and "FR-CA" becomes "fr_CA". If the request does not include the Accept-Language header then the Locale is the default Locale for the server.

<example> <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <rewrite-dispatch> <forward regexp='^/' target='/fr/'> <when locale="^fr"/> </forward> <forward regexp='^/' target='/en/'/> </rewrite-dispatch> </web-app>
locale Regular expression to match required
send-vary Send a `Vary` header containing "`Accept-Language`" as part of the response true
<parents>when, unless</parents>

Evaluates to true if the value of the request's local port is the specified value, false if it does not. The local port is the port that Resin has bound to and has used to receive the request.

local-port The local port to match. required
<parents>when, unless</parents>

Evaluates to true if the http method used in the request is the given value. The comparison is always case insensitive. Common methods include HEAD, GET, POST, DELETE, OPTIONS, PUT, and TRACE, although a method by any name may be used by a client.

method The method to match. required
<parents>rewrite-dispatch, match</parents>

<match> provides a way to group more specific rules based on the url. The contents of the <match> are any rule, and they are considered only if the regexp of the <match> is satsified and the match is enabled.

Judicious use of <match> will provide better performance in situations where there are many rules and some of them contain when or if conditions.

<match> also provides a convenient way to group a set of rules that can be enabled or disabled using an mbean. If the name attribute is specified for the <match> then an mbean with a name like `resin:Host=default,WebApp=/,name=name,type=RewriteRule` is registered and the `start()` and `stop()` operations are available.

The documentation for <rewrite-dispatch> provides a table of all rules. In addition to the rules that can be contained within <match>, the following configuration tags are available.

disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>rewrite-dispatch, match</parents>

<moved-permanently> sends a HTTP 301 moved permanently response to the browser, indicating that the resource has moved.

The following example causes all requests to the "old.com" host to be immediately redirected to "new.com". The urls will be maintained, so for example a request to `http://old.com/hello/world.html?foo=bar` will get redirected to `http://new.com/hello/world.html?foo=bar`.

<host id="old.com"> <web-app id="/"> <rewrite-dispatch> <moved-permanently regexp="^/(.*)$" target="http://new.com/$1"/> </rewrite-dispatch> </web-app> </host>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional

A rule can be given a name, which causes a JMX mbean to be registered. The mbean has a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule" and an interface of . It provides the `start()` and `stop()` operations.

<parents>when, unless</parents>

Contains one or more conditions and evaluates to true only if none of the contained conditions evaluate to true, false if any of the contained conditions evaluate to true.

<parents>when, unless</parents>

Contains one or more conditions and evaluates to true if any of the contained conditions evaluate to true, false only if all of the contained conditions evaluate to false.

<parents>rewrite-dispatch, match</parents>

<not-found> sents a 404 not found to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <not-found regexp="^/protected"/> </rewrite-dispatch> </web-app>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>when, unless</parents>

Evaluates to true if the value of a query parameter with a given matches a regular expression , false if it does not or if the parameter does not exist.

Form parameters submitted in the body of a POST are not available for the comparison performed by query-param.

query-param Name of the parameter required
regexp The regular expression to match optional
<parents>rewrite-dispatch, match</parents>

<redirect> sends a HTTP 302 redirect response to the browser, indicating that the resource has moved.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <redirect regexp="^/(foo)" target="http://$1.bar.com"/> </rewrite-dispatch> </web-app> <host ... > <rewrite-dispatch> <redirect regexp="^" target="https://${host.name}"> <when secure="false"/> </redirect> </rewrite-dispatch> ... </host>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional
<parents>when, unless</parents>

Evaluates to true if the remote address of the client matches the specified ip address.

A `Cache-Control` header containing "`private`" is added to the response.

<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <rewrite-dispatch> <forbidden regexp='^/foo'> <unless remote-addr="192.168.2.1/24"/> </forbidden> </rewrite-dispatch> </web-app>
remote-addr An IP address, optionally followed by a `/` and a number of bits to match. required
<parents>when, unless</parents>

Evaluates to true if the user is authenticated and has the specified name.

If there is a current user, a `Cache-Control` header containing "`private`" is added to the response.

remote-user A user name. required
send-vary Send a `Vary` header containing "`Cookie`" as part of the response true
<parents>rewrite-dispatch, match</parents>

<rewrite> rewrites the current URL, continuing processing of the <rewrite-dispatch> tags. <rewrite> can be used as an intermediate rewriting stage for more complicated patterns.

<parents>web-app</parents>

<rewrite-real-path> configures an alias for the getRealPath() call, i.e. an enhancement to the <path-mapping> tag. It provides a virtual directory mapping that allows url patterns in the web application to have a local path anywhere on the physical filesystem.

The source path is a URL, the target path is a real filesystem path.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/images" target="/usr/local/share/images"/> </rewrite-real-path> <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/" target="WEB-INF/SugarCE-Full-5.0.0a"/> </rewrite-real-path>

A merge path is a collection of paths, similar to a classpath. It allows the specification of multiple paths that are merged together and presented to the application as if it was one unified path. Merge paths are specified with a syntax of "`merge:(path1[;path2[;pathN]])`". If a file is in `path1` it overrides a file with the same name in `path2`, if a file is not in `path1` then the file will be matched to `path2`.

Merge paths are useful for specifying customization directories that allow for the insertion of files that replace the usual file that is shipped with a web application.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/images" target="merge:(custom-images;images)"/> </rewrite-real-path> <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/" target="merge:(WEB-INF/SugarCE-local;WEB-INF/SugarCE-Full-5.0.0a)"/> </rewrite-real-path> <parents>server, host, web-app</parents>

<rewrite-dispatch> evaluates the child tags in order. The first matching tag dispatches the request. If no children match, the request uses the standard servlet handling.

The child tags rewrite and dispatch based on regexp patterns.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <dispatch regexp="\.(php|gif|css|jpg|png)"/> <forward regexp="^" target="/index.php"/> </rewrite-dispatch> </web-app>
<dispatch> Dispatch the request immediately and do not process any more rules
<forbidden> Send a 403 Forbidden response to browser and do not process any more rules
<forward> Rewrite the URL and internally forward the request without processing any more rules
<forbidden> Send a 410 Gone response to the browser and do not process any more rules
<import> Import rules from an external file
<load-balance> Forward requests to another instance or instances of Resin and do not process any more rules
<match> Group more specific rules
<moved-permanently> Send a 310 Moved Permanently response to the browser and do not process any more rules
<redirect> Send a 302 Moved response to the browser and do not process any more rules
<rewrite> Rewrite the current URL and continue processing rules
<set> Set a property of the request or response and continue processing rules
<parents>when, unless</parents>

<secure> specifies a condition for the ssl status of the request. If is true, then the request must be using ssl for the rule to match. If is false, then the request must not be using ssl for the rule to match. If is not specified, the ssl status of the request is not considered when testing if the rule matches.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <redirect regexp='^/foo' target='/secure'> <when secure='true'/> </redirect> <redirect regexp='^/foo' target='/insecure'> <when secure='false'/> </redirect> <redirect regexp='^/bar' target='/public'/> </rewrite-dispatch> </web-app> <results> http://localhost:8080/foo/index.html --> redirect to /insecure/index.html https://localhost:8080/foo/index.html --> redirect to /secure/index.html http://localhost:8080/bar/index.html --> redirect to /public/index.html https://localhost:8080/bar/index.html --> redirect to /public/index.html </results> <parents>when, unless</parents>

Evaluates to true if the value of the request's server name matches the specified regexp, false if it does not. The comparison is always case insensitive. The server name is the name that the client has used to connect to the server and may not be the name of the actual server that is hosting Resin.

Most potential problems that can be solved by `server-name` are more efficiently solved using <g>virtual hosts</g> and the host-alias tag.

server-name A regular expression to match. required
<parents>when, unless</parents>

Evaluates to true if the value of the request's server port is the specified value, false if it does not. The server port is the port that the client has used to connect to the server and may not be the actual port that Resin is bound to.

server-port The server port to match. required
<parents>rewrite-dispatch, match</parents>

<set> is used to set properties of the request or response before continuing on to the next rule. The properties are maintained after the rewriting is complete, for example a request that becomes secure because of <set> will continue to be regarded as secure when the request eventually reaches a jsp or servlet.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <set request-secure="true"> <when header="X-SSL-cipher"/> </set> <forward regexp="^/checkout" target="https://hogwarts.com/checkout"> <when secure="false"/> </forward> </rewrite-dispatch> </web-app>
disable-at A cron syntax time specification for triggering disablement of the rule none
enable-at A cron syntax time specification for triggering enablement of the rule none
enabled False to start with the rule initially disabled true
name A name to use for registering a JMX mbean with type=RewriteRule do not register an mbean
regexp A regexp that must match the URL optional
request-character-encoding Sets the character encoding of the request, used for parsing POST data, request.setCharacterEncoding(value) none
request-secure Sets the value of request.isSecure() none
response-character-encoding Sets the value of the character encoding sent for the response with response.setCharacterEncoding(value). If a Content-Type is not set either with a set rule, or by some other process involved in servicing the request, this has no effect. none
response-content-type Sets the value of the content type sent for the response. If the final destination is a file with a corresponding mime-mapping, the mime-mapping will override the content-type set here none
when A condition which must evaluate to true optional
unless A condition which must not evaluate to true optional

Contains a condition that further refines the match of the enclosing tag beyond the information provided by the url. If the condition does not evaluate to true, then the enclosing tag is applied.

See <when> for a description of possible conditions.

<parents>when, unless</parents>

Evaluates to true if the user is authenticated and in the specified role. The special role of '*' means any role.

If the current user is any role, a `Cache-Control` header containing "`private`" is added to the response.

user-in-role A role name. required
send-vary Send a `Vary` header containing "`Cookie`" as part of the response true

Contains a condition that further refines the match of the enclosing tag beyond the information provided by the url. If the condition evaluates to true, then the enclosing tag is applied.

<and> A subgroup of conditions that must all pass
auth-type Evaluates to true if the authorization mechanism used in the request is the given value
cookie Evaluates to true if a cookie exists and matches an optional
header Evaluates to true if a request header exists and matches an optional
locale Evaluates to true if the request locale matches the specified value
local-port Evaluates to true if the local port is the specified value (the local port is the actual port that Resin is using)
method Evaluates to true if the http method used for the request is the specified value
<not> A subgroup of conditions, none of which may pass
<or> A subgroup of conditions, any of which may pass
query-param Evaluates to true if a query parameter exists and matches an optional
regexp Used in conjunction with , , and
remote-addr Evaluates to true if the remote address of the client matches the specified ip address
remote-user Evaluates to true if the user is authenticated and has the specified name
secure Evaluates to true if the ssl status of the request is equal to the specified value of true or false
server-name Evaluates to true if the server name used by the client matches the specified value
server-port Evaluates to true if the port used by the client equals the specified value
user-in-role Evaluates to true if the user is authenticated and in the specified role

Logging for the name `com.caucho.server.rewrite` at the "finer" level reveals successful matches. At the "finest" level both successful and unsuccessful matches are logged.

<logger name="com.caucho.server.rewrite" level="finest"/> <results> [1998/05/08 02:51:31.000] forward ^/foo: '/baz/test.jsp' no match [1998/05/08 02:51:31.000] forward ^/bar: '/baz/test.jsp' no match [1998/05/08 02:51:31.000] forward ^/baz: '/baz/test.jsp' --> '/hogwarts/test.jsp' </results>

The desired behaviour is to redirect plain connections to SSL connections.

http://anything.com/anything.html redirect => https://anything.com/anything.html <host ...> ... <rewrite-dispatch> <redirect regexp="^" target="https://${host.name}"> <when secure="false"/> </redirect> </rewrite-dispatch> ... </host>

The desired behaviour is to internally forward requests based on the host name.

http://gryffindor.hogwarts.com/anything.html forward => /gryffindor/* http://slytherin.hogwarts.com/anything.html forward => /slytherin/anything.html http://hogwarts.com/anything.html forward => /anything.html

The rewrite-dispatch tag is used at the <cluster> level. If it was placed in the <host> or the <web-app> then it would be too late to forward to a different host because Resin would have already resolved the host.

<cluster> ... <rewrite-dispatch> <forward regexp="http://gryffindor\.[^/]+" target="/gryffindor/"/> <forward regexp="http://slytherin\.[^/]+" target="/slytherin/"/> </rewrite-dispatch> ... </cluster>
</document>