Running The TDS Behind a Proxy Server

Uses of reverse proxies

• A reverse proxy is a proxy server that appears to clients to be an ordinary server. Requests are forwarded to one or more origin servers which handle the request. The response is returned as if it came directly from the proxy server.

• Reverse proxies can be used to hide the existence and characteristics of the origin server(s) and can be an additional layer of defense and can protect against some OS and WebServer specific attacks. However, it does not provide any protection to attacks against vulernabilities in the web application or proxy service itself (e.g., Apache, Tomcat).
• A reverse proxy can also be used for load balancing, caching content, content compression, and SSL acceleration.

Using Tomcat and Apache HTTP Server

• Using Apache as a front-end proxy server for the TDS running on Tomcat is perhaps the easiest method for setting up a reverse proxy for the TDS. There are two methods to accomplish this:
• Apache's mod_proxy in combination with Tomcat's HTTP connector; or
• the mod_jk Apache module with the Tomcat AJP connector.
• Warning! It is important to carefully configure your proxy so that the existence of the proxy is transparent to the end-user/client. For instance, when a web application (e.g., the TDS) on the backend server includes a self-referential URL in some response content, it should use the proxy server's name and port rather than those of the backend server.

Tomcat-Apache Proxy Documentation

• Tomcat Connectors
  Documentation describing the difference between the Tomcat HTTP and AJP connectors.
• mod_proxy
• Tomcat HTTP Connector
  Configuration for the Tomcat HTTP connector (for use with Apache's mod_proxy).
• Tomcat Proxy Support - How To
  Tomcat documentation showing how to use the build-in Apache module mod_proxy for Apache versions 1.3X and 2.X.
• mod_jk
• Tomcat AJP Connector
  Configuration for the Tomcat AJP connector (for use with Apache's mod_jk).
• Tomcat Reverse Proxy - How To
  Configurations and fine tuning of a reverse proxy set up using the mod_jk Apache module.

Changing the TDS Context Path ( /thredds )

We do not recommend changing the TDS context path (the /thredds part of the URL path). However, if your network configuration requires that you use a different context path (e.g., /my/thredds ) or you are proxying two TDS installations and need to differentiate them with different context paths (e.g., /thredds1 and /thredds2 ), you will need to make the following changes:

1. Rename the thredds.war file to match the desired context path before you deploy it to Tomcat.

Tomcat and other servlet engines direct incoming requests to a particular web application when the beginning of the request URL path matches the context path of that particular webapp. The easiest way to let Tomcat (or any other servlet engine) know what context path to use for a given webapp is to rename that webapp's .war file before deploying it to Tomcat.

For instance, if you want all URLs starting with /thredds2 to be handled by your TDS install, rename the thredds.war file to thredds2.war before you deploy it to Tomcat.

If the desired context path is a multi-level context path (e.g., /my/thredds ), you must use a pound sign ("#") in the .war filename to encode the slash ("/"). In this case, the thredds.war file would need to be renamed to my#thredds.war .

Keep in mind

The deployment descriptor ( web.xml file) is overwritten during deployment which means this edit must be done every time the TDS is re-deployed.

2. Edit the TDS web.xml file and change the value of the "ContextPath" parameter to match the desired context path.

The TDS uses the value of the "ContextPath" context parameter (as defined in the TDS web.xml file) when generating TDS URLs in certain situations. To make sure all generated URLs are consistent, you must change the value of the "ContextPath" parameter to match the desired context path.

(Changing the value of "ContextPath" will no longer be necessary in a future release once we require Tomcat 6.0 (Servlet 2.5).

The TDS web.xml file is located in ${tomcat_home}/webapps/<contextPath>/WEB-INF/web.xml , where <contextPath> is the value of the desired context path. The "ContextPath" context parameter is defined in the web.xml file (starting at line 12):

<context-param>
  <param-name>ContextPath</param-name>
  <param-value>thredds</param-value>
</context-param>

For the /thredds2 example, it should be changed to:

<context-param>
  <param-name>ContextPath</param-name>
  <param-value>thredds2</param-value>
</context-param>

And for the /my/thredds example, it should be changed to:

<context-param>
  <param-name>ContextPath</param-name>
  <param-value>my/thredds</param-value>
</context-param>

3. Edit your TDS configuration catalogs and change the service base URLs to start with the desired context path

So that users will receive the correct data access URLs for datasets served by your TDS, the base URLs given by the service elements in your TDS configuration catalogs must match the desired context path.

An OPeNDAP service element on a TDS with the context path of /thredds2 would need to look similar to this:

<service name="odap" serviceType="OPeNDAP" base="/thredds2/dodsC/"/>

And similarly, an OPeNDAP service element on a TDS with the context path of /my/thredds would need to look similar to this:

<service name="odap" serviceType="OPeNDAP" base="/my/thredds/dodsC/"/>