![]() | ![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation examples changes overview quick start installation command-line configuration admin amber clustering caching database deployment ejb 3.0 embedding filters hessian hmtp ioc jsp logging messaging performance quercus/php remoting scheduled tasks security server push servlets third-party troubleshooting virtual hosting watchdog webapp xml and xslt <cluster> <database> <host> ports <resin> resource tags rewrite <server> session variables <web-app> index relax schema | url rewrite tags
Resin's <rewrite-dispatch> tag allows configuration for URL aliasing, rewriting, dispatching, and redirection. <rewrite-real-path> configures an alias for files located on the filesystem, allowing for the mapping of a virtual directory.
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. child of when, unlessEvaluates 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
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.
Cron syntax for specifying a time or times that that the rule should be disabled. In conjunction, and provide a means for scheduling the enablement of a rule. child of rewrite-dispatch, matchIf <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. Mediawiki dispatch in resin-web.xml <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>
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. child of rewrite-dispatch, match<forbidden> sents a 403 forbidden message to the browser for a matching URL. Forbidding a directory <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <forbidden regexp="^/protected"/> </rewrite-dispatch> </web-app>
<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. Forwarding to a new URL <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <forward regexp="^/old" target="/new"/> </rewrite-dispatch> </web-app>
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.
<gone> sents a 410 gone response to the browser for a matching URL. Hiding a directory <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <gone regexp="^/protected"/> </rewrite-dispatch> </web-app>
<import> loads rules from an external xml file. Importing rules from an external 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> An external file containing rules <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
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 com.caucho.management.server.RewriteImportMXBean.
It provides the
<load-balance> forwards requests from a web-tier server to a cluster of app-tier 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. Load balancing to an app-tier <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>
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. <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>
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.
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.
<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 .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 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.
<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 Forwarding to a new virtual host <host id="old.com"> <web-app id="/"> <rewrite-dispatch> <moved-permanently regexp="^/(.*)$" target="http://new.com/$1"/> </rewrite-dispatch> </web-app> </host>
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 com.caucho.management.server.RewriteRuleMXBean.
It provides the 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. child of when, unlessContains 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. child of rewrite-dispatch, match<not-found> sents a 404 not found to the browser for a matching URL. Hiding a directory <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <not-found regexp="^/protected"/> </rewrite-dispatch> </web-app>
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.
<redirect> sends a HTTP 302 redirect response to the browser, indicating that the resource has moved. Forwarding to a new virtual host <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <redirect regexp="^/(foo)" target="http://$1.bar.com"/> </rewrite-dispatch> </web-app> Redirecting all http:// requests to https:// <host ... > <rewrite-dispatch> <redirect regexp="^" target="https://${host.name}"> <when secure="false"/> </redirect> </rewrite-dispatch> ... </host>
Evaluates to true if the remote address of the client matches the specified ip address.
A Forbidding admin access to clients outside of the local network <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>
Evaluates to true if the user is authenticated and has the specified name.
If there is a current user, a
<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. child of web-app<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. /images located outside of /var/www <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/images" target="/usr/local/share/images"/> </rewrite-real-path> Managing versions of software bundles <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> Merge paths
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 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. Merge path: replacing some images with custom images <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/images" target="merge:(custom-images;images)"/> </rewrite-real-path> Merge path: managing the versioning and customization of a php application <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> <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. Mediawiki dispatch in resin-web.xml <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>
<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.secure example <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> 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 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
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.
<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. Making the request secure in response to a header from a hardware load balancer <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>
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. child of when, unlessEvaluates 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
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.
Logging for the name Logging example <logger name="com.caucho.server.rewrite" level="finest"/> [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' Redirect http:// requests to https:// requestsThe desired behaviour is to redirect plain connections to SSL connections. Desired behaviour http://anything.com/anything.html redirect => https://anything.com/anything.html Configuration <host ...> ... <rewrite-dispatch> <redirect regexp="^" target="https://${host.name}"> <when secure="false"/> </redirect> </rewrite-dispatch> ... </host> Forward based on host nameThe desired behaviour is to internally forward requests based on the host name. Desired behaviour 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. Configuration <cluster> ... <rewrite-dispatch> <forward regexp="http://gryffindor\.[^/]+" target="/gryffindor/"/> <forward regexp="http://slytherin\.[^/]+" target="/slytherin/"/> </rewrite-dispatch> ... </cluster>
|