Proxy Support HOW-TO

Tableof Contents

• Introduction
• Apache 1.3 ProxySupport
• Apache 2.0 ProxySupport

Introduction

Using standard configurations of Tomcat, web applications canask for the server name and port number to which the request wasdirected for processing. When Tomcat is running standalone with theCoyote HTTP/1.1Connector, it will generally report the server name specifiedin the request, and the port number on which theConnector is listening. The servlet API calls ofinterest, for this purpose, are:

• ServletRequest.getServerName(): Returns the hostname of the server to which the request was sent.
• ServletRequest.getServerPort(): Returns the hostname of the server to which the request was sent.
• ServletRequest.getLocalName(): Returns the hostname of the Internet Protocol (IP) interface on which the requestwas received.
• ServletRequest.getLocalPort(): Returns theInternet Protocol (IP) port number of the interface on which therequest was received.

When you are running behind a proxy server (or a web server thatis configured to behave like a proxy server), you will sometimesprefer to manage the values returned by these calls. In particular,you will generally want the port number to reflect that specifiedin the original request, not the one on which theConnector itself is listening. You can use theproxyName and proxyPort attributes on the<Connector> element toconfigure these values.

Proxy support can take many forms. The following sectionsdescribe proxy configurations for several common cases.

Apache 1.3 ProxySupport

Apache 1.3 supports an optional module (mod_proxy)that configures the web server to act as a proxy server. This canbe used to forward requests for a particular web application to aTomcat instance, without having to configure a web connector suchas mod_jk. To accomplish this, you need to perform thefollowing tasks:

1. Configure your copy of Apache so that it includes themod_proxy module. If you are building from source, theeasiest way to do this is to include the--enable-module=proxy directive on the./configure command line.
2. If not already added for you, make sure that you are loadingthe mod_proxy module at Apache startup time, by usingthe following directives in your httpd.conf file:

   
   
   

   

   LoadModule proxy_module {path-to-modules}/mod_proxy.so AddModule mod_proxy.c

   
   

   
   
   

3. Include two directives in your httpd.conf file foreach web application that you wish to forward to Tomcat. Forexample, to forward an application at context path/myapp:

   
   
   

   

   ProxyPass /myapp http://localhost:8081/myapp ProxyPassReverse /myapp http://localhost:8081/myapp

   
   

   
   
   

   which tells Apache to forward URLs of the formhttp://localhost/myapp/* to the Tomcat connectorlistening on port 8081.

4. Configure your copy of Tomcat to include a special<Connector> element,with appropriate proxy settings, for example:

   
   
   

   

   <Connector port="8081" ... proxyName="www.mycompany.com" proxyPort="80"/>

   
   

   
   
   

   which will cause servlets inside this web application to thinkthat all proxied requests were directed towww.mycompany.com on port 80.

5. It is legal to omit the proxyName attribute fromthe <Connector> element.If you do so, the value returned byrequest.getServerName() will by the host name on whichTomcat is running. In the example above, it would belocalhost.
6. If you also have a<Connector> listening onport 8080 (nested within the same Service element),the requests to either port will share the same set of virtualhosts and web applications.
7. You might wish to use the IP filtering features of youroperating system to restrict connections to port 8081 (in thisexample) to be allowed only from the server thatis running Apache.
8. Alternatively, you can set up a series of web applications thatare only available via proxying, as follows:
   • Configure another<Service> that containsonly a <Connector> forthe proxy port.
   • Configure appropriate Engine, Host, and Context elementsfor the virtual hosts and web applications accessible viaproxying.
   • Optionally, protect port 8081 with IP filters as describedearlier.
9. When requests are proxied by Apache, the web server will berecording these requests in its access log. Therefore, you willgenerally want to disable any access logging performed by Tomcatitself.

When requests are proxied in this manner, allrequests for the configured web applications will be processed byTomcat (including requests for static content). You can improveperformance by using the mod_jk web connector insteadof mod_proxy. mod_jk can be configured sothat the web server serves static content that is not processed byfilters or security constraints defined within the webapplication's deployment descriptor(/WEB-INF/web.xml).

Apache 2.0 ProxySupport

The same instructions hold true as for 1.3. (Except inApache 2.0, you may omit AddModulemod_proxy.c)