The Tomcat 5 Servlet/JSP Container

Load Balancer HOW-TO

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.

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 www.cnn.com
• Redirect requests with a parameter named paramName whose value is paramValue to www.yahoo.com.
• Redirect all other requests to jakarta.apache.org.

Therefore, when you install tomcat, start it, and point your browser to http://localhost:8080/balancer, you will be redirected to http://jakarta.apache.org. If you point your browser to http://localhost:8080/balancer/News you will be redirected to http://www.cnn.com. The request for http://localhost:8080/balancer/BlahBlah?paramName=paramValue will be redirected to http://www.yahoo.com.

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 of 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.

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.