Apache Tomcat Proxy Configuration

Although Apache Tomcat has the ability to function as a standalone HTTP server via the Coyote HTTP/1.1 Connector component, many administrators also front their Tomcat instances with a proxy server.  Common reasons to use a proxy server with Tomcat include security, load balancing, extended functionality (such as URL re-writing), and content caching.

In this article, we'll cover everything you need to know about using Tomcat in conjunction with a proxy - a comparison of the proxy servers most commonly used with Tomcat, sample configurations, and a look at how Tcat, the enterprise version of Apache Tomcat, takes the pain out of Tomcat proxy configuration.

Choosing A Proxy Solution 

There are lots of options when it comes to choosing a proxy solution for your Tomcat servers, Apache HTTPD, HAProxy, and NGiNX are currently some of the most commonly used all-around open source solutions.  These projects are sometimes used in conjunction with others, such as Pound and Varnish, which are more specialized.  In some cases, these solutions are layered to take advantage of the different abilities of each - for example, Tomcat clusters fronted with Apache for load balancing and security, and Varnish for caching.   

Apache HTTPD is battle-tested, familiar to most administrators, flush with community-created modules that can be used to quickly extend Tomcat's capabilities as needed, and integrated with Tomcat via the Tomcat Connectors project, also known as mod_jk.  Clusters of Tomcat servers behind an Apache HTTPD instance providing load balancing is a very common set-up, both in traditional infrastructures and in the cloud.

HAProxy is a proxy server designed specifically to provide fast, resilient, high availability load balancing for app servers.  HAProxy uses an event-driven architecture instead of threads, which in theory allows it to handle a greater number of simultaneous connections without collapsing.  HAProxy is commonly used to provide load balancing for content rich sites that have to stand up against sudden peaks of traffic directed at a small number of pages.  

NGiNX is a very fast web and proxy server, which, like HAProxy, uses an event-driven architecture to stand up against big traffic spikes.  Typically, administrators dealing with high load scenarios test both nginx and HAProxy, as they have been known to outperform one another on a raw throughput basis depending on the nature of the site.  NGiNX is somewhat smaller than HAProxy, with a more primitive load balancing implementation (which can sometimes gives it an advantage from a resource usage perspective).

Other projects, such as Varnish and Pound, offer features which may be attractive for more specific scenarios.  Pound is specifically to implement security, and as such optimized includes optimized HTTPS decoding capabilities along with load balancing/failover.  Varnish is designed strictly to accelerate/cache web content, and as such must be used in conjunction with another solution if load balancing or security features are desired.

As with any technical decision, when choosing a proxy solution, there's no substitute for thorough testing.  Know your needs, create a few optimized configurations using different combinations of solutions, and pick the one that works best for your site and its traffic patterns.


Once you've determined which proxy server is best suited to your needs, you'll need to configure it to work with your Tomcat instances.  This is a two part process - configuring Tomcat to communicate with the proxy server, and configuring the proxy server to communicate with Tomcat.  

In this section, we'll cover bare-bones configurations for Apache HTTPD, HAProxy, and nginx.  Almost every use case will require additional configuration to implement things such as clustering, logging, and security,  which are too technical and site-specific to be usefully covered in a lightweight discussion, but these examples will get you through the first steps to get your proxy server and your Tomcats talking to each other.

Configuring Tomcat To Use A Proxy

Tomcat contexts can be configured to expect proxied requests using a connector element with the appropriate proxy-specific attributes configured:

<Connector port="8082"...



The values of these attributes should match the values you have configured within your proxy server.

It's also possible to configure an entire set of web applications to only be accessible through a proxy, by creating a new Service with only a proxy Connector configured.

For more detailed information about configuring Tomcat to use a proxy server, visit the official documentation.

Configuring Apache HTTPD

Apache HTTPD can be connected to Tomcat with the help of a number of modules designed for this purpose.  Although there are actually 6 or 7 modules to choose from, many of these are deprecated, not supported, or generally unstable.  There are actually only three modules you should use:  mod_jk, mod_proxy_http, or mod_proxy_ajp.  

Each of these modules has slightly different capabilities, but very similar performance, to the extent that deciding between them is as much a matter of whether or not you're already using one of them as it is anything else.  One major difference is protocol - mod_proxy_http uses the HTTP protocol, which supports HTTPS, whereas mod_jk and mod_proxy_ajp use the AJP protocol, a binary form of HTTP with no native encryption support.  However, this can be implemented without too much trouble using an SSH tunnel or something similar.

For information on the differences between these modules, as well as easy step by step configuration instructions, you can visit the mod_jk connector configuration article, a part of MuleSoft's Apache Tomcat Resource Center.

Configuration of mod_proxy_http and mod_proxy_ajp is accomplished using the standard HTTPD directive format.  Below, you can find links to the official HTTPD documentation of this format, as well as the directives for each of the modules:

Configuring HAProxy

HAProxy is configured via command-line commands and a single configuration file with two sections - "global", which contains global settings for all instances, and "proxies" sections which are used to configure HAProxy's capabilities for all the types of servers that it will communicate with.

The HAProxy project site provides thorough documentation, including:

Configuring NGiNX

The official NGiNX wiki includes full documentation for NGiNX, including:

When using NGiNX with Tomcat, it is ESSENTIAL to use the Tomcat Native Connectors package appropriate for your server's OS.  Failing to do so will result significant impacts to performance.  

If you are not familiar with the Tomcat Native connector, check out the official documentation, which provides thorough installation and configuration instructions.

Further Reading

If you'd like more information about clustering and load balancing Tomcat, you can check out the articles on the subject in MuleSoft's Apache Tomcat Resource Center, including an introduction to clustering, and an example clustered configuration using two Tomcat instances and Apache HTTPD.

For detailed information about how you can secure your web applications using a proxy server, check out our articles on Tomcat Web App Security and Tomcat Security Best Practices.

Tcat Makes Proxy Configuration Simple

Tcat is the enterprise version of Apache Tomcat.  Starting with 100% unmodified Apache Tomcat, Tcat adds the monitoring, management, deployment, and configuration features that are required to use Tomcat in the enterprise production environment.

One feature of Tcat is the ability to create and save a Server Profile - a template configuration that can be applied to new instances with a single click.  For example, when configuring your proxy server, rather than manually logging into each of your Tomcat instances and editing their configuration files, you could create a single server profile, and then enforce it across your entire infrastructure.  Tcat's reliable remote restarts allow you to quickly see the effects of configuration changes.

Tcat also provides unparalleled visibility into the performance of your infrastructure.  This is especially helpful when tuning your proxied instances or evaluating the performance of two solutions against one another. Rather than reaching for another tool, you can simply switch to Tcat monitoring console, which provides deep, detailed, real-time statistics about the performance of your webapps, Tomcat instances, and JVM.   

Strapped for time? No problem! click here to download Tcat.