Jetty/Feature/Rewrite Handler

Introduction

Jetty 7 and Jetty 8 are now EOL (End of Life)

THIS IS NOT THE DOCUMENTATION YOU ARE LOOKING FOR!!!!!

All development and stable releases are being performed with Jetty 9 and Jetty 10.

This wiki is now officially out of date and all content has been moved to the Jetty Documentation Hub

Direct Link to updated documentation: http://www.eclipse.org/jetty/documentation/current/rewrite-handler.html

The RewriteHandler matches a request against a set of rules, and modifies the request accordingly for any rules that match. The most common use is to rewrite request URIs, but it is capable of much more: rules can also be configured to redirect the response, set a cookie or response code on the response, modify the header, etc.

Feature

Quick Start

The standard Jetty distribution bundle contains the jetty-rewrite module JAR, at lib/jetty-rewrite-*.jar, and a sample configuration file, at etc/jetty-rewrite.xml. To enable the rewrite module, using the sample configuration file, start up Jetty with this command:

 java -jar start.jar OPTIONS=default,rewrite etc/jetty.xml etc/jetty-rewrite.xml

Rewrite Module Demo
If you are running the standard Jetty distribution with the sample test webapp, there will be a demo of the rewrite module at http://localhost:8080/rewrite/

Configuring Rules

Configuration File Example

The rules are configured using jetty.xml syntax. This example file shows how to add the rewrite handler for the entire server:

  <Configure id="Server" class="org.eclipse.jetty.server.Server">
    <!-- create and configure the rewrite handler -->
    <New id="Rewrite" class="org.eclipse.jetty.rewrite.handler.RewriteHandler">
      <Set name="rewriteRequestURI">true</Set>
      <Set name="rewritePathInfo">false</Set>
      <Set name="originalPathAttribute">requestedPath</Set>
 
      <!-- redirect the response. This is a redirect which is visible to the browser.
           After the redirect, the browser address bar will show /redirected -->
      <Call name="addRule">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RedirectPatternRule">
            <Set name="pattern">/redirect/*</Set>
            <Set name="location">/redirected</Set>
          </New>
        </Arg>
      </Call>
 
      <!-- This rewrites the base URL; supports Regex. This is visible to the browser. -->
      <Call name="addRule">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RedirectRegexRule">
            <Set name="regex">(^(?!/base/path/).*)</Set>
            <Set name="replacement">/base/path/</Set>
          </New>
        </Arg>
      </Call>
    </New>
 
      <!-- rewrite the request URI. This is an internal rewrite, visible to server,
           but the browser will still show /some/old/context -->
      <Call name="addRule">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule">
            <Set name="pattern">/some/old/context</Set>
            <Set name="replacement">/some/new/context</Set>
          </New>
        </Arg>
      </Call>
 
      <!-- reverse the order of the path sections. Internal rewrite -->
      <Call name="addRule">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RewriteRegexRule">
            <Set name="regex">/reverse/([^/]*)/(.*)</Set>
            <Set name="replacement">/reverse/$2/$1</Set>
          </New>
        </Arg>
      </Call>
    </New>
 
     <!-- add the rewrite handler to the server -->
    <Set name="handler"><Ref id="Rewrite" /></Set>
  </Configure>

See jetty-rewrite.xml for more configuration examples.

Embedded Example

This is an example for embedded Jetty, which does the same thing as the configuration file example above:

  Server server = new Server();
 
  RewriteHandler rewrite = new RewriteHandler();
  rewrite.setRewriteRequestURI(true);
  rewrite.setRewritePathInfo(false);
  rewrite.originalPathAttribute("requestedPath");
 
  RedirectPatternRule redirect = new RedirectPatternRule();
  redirect.setPattern("/redirect/*");
  redirect.setReplacement("/redirected");  
  rewrite.addRule(redirect);
 
  RewritePatternRule oldToNew = new RewritePatternRule();
  oldToNew.setPattern("/some/old/context");
  oldToNew.setReplacement("/some/new/context");
  rewrite.addRule(oldToNew);
 
  RewriteRegexRule reverse = new RewriteRegexRule();
  reverse.setRegex("/reverse/([^/]*)/(.*)");
  reverse.setReplacement("/reverse/$2/$1");
  rewrite.addRule(reverse);
 
  server.setHandler(rewrite);

Rules

PatternRule

Matches against the request URI using the servlet pattern syntax.

CookiePatternRule: Adds a cookie to the response.
HeaderPatternRule: Adds/modifies a header in the response.
RedirectPatternRule: Redirects the response.
ResponsePatternRule: Sends the response code (status or error).
RewritePatternRule: Rewrite the URI by replacing the matched request path with a fixed string.

RegexRule

Matches against the request URI using regular expressions.

RedirectRegexRule: Redirect the response.
RewriteRegexRule: Rewrite the URI by matching with a regular expression. (The replacement string may use Template:$n to replace the nth capture group.)

HeaderRule

Match against request headers. Match either on a header name + specific value, or on the presence of a header (with any value).

ForwardedSchemeHeaderRule: Set the scheme on the request (defaulting to https).

Others

MsieSslRule: Disables the keep alive for SSL from IE5 or IE6.
LegacyRule: Implements the legacy API of RewriteHandler

RuleContainer

Groups rules together. The contained rules will only be processed if the conditions for the RuleContainer evaluate to true.

VirtualHostRuleContainer: Groups rules that apply only to a specific virtual host or a set of virtual hosts

Breadcrumbs