The Apache Tomcat Servlet/JSP Container

The Apache Tomcat 5.5 Servlet/JSP Container

Apache Logo


User Guide


Apache Tomcat Development

The Apache Tomcat 5.5 Servlet/JSP Container

Load Balancer HOW-TO

Printer Friendly Version
Table of Contents

Using the JK native connector
Using Apache HTTP Server 2.x and mod_proxy
Using the balancer webapp

Using the JK 1.2.x native connector
Please refer to the JK 1.2.x documentation.
Using Apache HTTP Server 2.x with mod_proxy
Please refer to the mod_proxy documentation for Apache HTTP Server 2.2. This supports either HTTP or AJP load balancing. This new version of mod_proxy is also useable with Apache HTTP Server 2.0, but mod_proxy will have to be compiled separately using the code from Apache HTTP Server 2.2.
Using the balancer webapp

Tomcat 5.0.15 and later ships with a webapp named balancer. This is a simple implemention of a rules-based load balancer. It was not designed as a replacement for other load-balancing mechanisms used for high traffic environments. Rather, it is a simple, pure Java, easily extensible, and fast way to direct traffic among multiple servers.

Although balancer ships with Tomcat, it is not Tomcat-specific and runs on other containers without any modification. The balancer webapp requires a Servlet Specification 2.3 or later container if you wish to use a filter to redirect traffic. If you wish to redirect traffic using a servlet, you may use any servlet container.

Sample Configuration

The default balancer installation uses a single filter, BalancerFilter, mapped to all requests (url-pattern /*). The filter reads its rules from the location specified in the balancer deployment descriptor (web.xml file). The default rules are:

  • Redirect requests with News in the URL to
  • Redirect requests with a parameter named paramName whose value is paramValue to
  • Redirect all other requests to
Therefore, when you install tomcat, start it, and point your browser to http://localhost:8080/balancer, you will be redirected to If you point your browser to http://localhost:8080/balancer/News you will be redirected to The request for http://localhost:8080/balancer/BlahBlah?paramName=paramValue will be redirected to

Balancer Rules

A Rule in the balancer system is a combination of a request matching criterion and a redirection URL for matching requests. Rules implement the org.apache.webapp.balancer.Rule interface.

The balancer distribution contains a number of useful rules. The framework is also designed for easy extensibility so that you can write your own rules quickly. Rules should be JavaBeans (public no-args constructor, public setter method setXXX for property xxx), as they are instantiated by Jakarta Commons Digester. Feel free to inquire on the tomcat-user mailing list regarding the availability of rules or the inclusion of your rules in the distribution.

Rules are assembled into RuleChains. Each BalancerFilter (or Servlet/JSP) refers to one RuleChain when making its redirection decisions. Note that you are not restricted to having one filter mapped to /* as done in the sample configuration. You can configure as many filters as desired, using the full filter mapping possibilities defined in the Servlet Specification. Each filter will have its own RuleChain.

How it Works

  1. You write a rules configuration file containing various rules and redirection locations.
  2. You define the balancer filter in your web.xml, mapping it as desired (/* is a common use-case) and configuring it with your rules configuration file.
  3. The server is started, initializing the filter.
  4. A request comes into the server. The filter consults its rule chain to determine where to redirect the request. Rules are consulted in the order in which they are defined in the rules configuration file. The first matching rule will stop the evaluation and cause the request to be redirected.


Please direct questions, comments, suggestions, etc. to the tomcat-user mailing list. Thank you.

Copyright © 1999-2008, Apache Software Foundation