Reverse Proxy and Application Link Troubleshooting Guide

This document is a part of our Application Links Troubleshooting Guide and Proxying Atlassian Server applications.

What is a reverse proxy?

A reverse proxy sits in front of an application and directs incoming traffic to it. The most common reverse proxies are Apache, IIS, and Nginx.

Reverse proxies are used to:

• Provide an easy to remember URL without a port number (that is, port forwarding), such as https://jira.myCompany.com instead of http://192.168.1.100:8080. 
• Provide SSL encryption for the application; that is SSL terminates at the proxy, and communication between the proxy and the application is unsecured.
• Provide firewall, load-balancing, caching and other services.

Reverse proxies generally come in two flavors:

HTTP proxy

HTTP proxies communicate over HTTP with the application server. Common types of HTTP proxies are:

• Apache, using mod_proxy
• Nginx
• IIS, using Application Request Routing (ARR)

AJP proxy

The Apache JServ Protocol (AJP) is a binary protocol for communicating with an Apache Tomcat server. It provides greater integration between the application server and the reverse proxy. Common types of AJP proxies are:

• Apache, using mod_jk
• IIS, using AJP ISAPI extension

Which should you use in your environment?

Atlassian recommends the use of an HTTP proxy - they're easier to configure, and you can choose the front end you want to use.

Benefits of an HTTP proxy:

• Use any web server technology
• Minimal configuration required

Benefits of an AJP proxy:

• Tighter integration with Apache Tomcat - support for load balancing, proxy awareness
• More granular logging capabilities

Configuring Tomcat for use with an HTTP proxy

When using a reverse proxy, the application server (Tomcat) must be aware of the proxy to ensure that the correct addresses and URLs are sent back to the client. If this is not correctly set up, Tomcat will return the hostname and IP that it's listening on, rather than the address that clients use to access the application.

The most reliable way to configure your HTTP connector is to include the proxy information:

<Connector port="8080" connectionTimeout="20000" maxThreads="200" minSpareThreads="10"
    enableLookups="false" acceptCount="10" URIEncoding="UTF-8" 
    proxyName="atlassian.com" proxyPort="443" scheme="https" secure="true" />

The necessary attributes are proxyName , proxyPort , and scheme . Replace the values above with values suitable for your deployment.  

secure
Set this attribute to true if you wish to have calls to request.isSecure() to return true for requests received by this Connector. You would want this on an SSL Connector or a non SSL connector that is receiving data from a SSL accelerator, like a crypto card, a SSL appliance or even a webserver. The default value is false.

For more information on these attributes, please see the Apache Tomcat documentation .

These attributes also force outbound traffic from Apache to back to the client via the reverse proxy. You may wish to bypass the reverse proxy and create an unproxied Application Link instead.

It is possible to provide the correct headers to the application server by using ProxyPreserveHost (or the equivalent for your reverse proxy). Making the modifications to the connector ensures that the application server responds correctly, regardless of the reverse proxy type or configuration.

Configuring Tomcat for use with an AJP proxy

Because the AJP protocol is a binary protocol that offers tighter integration with Apache Tomcat, most problems with AJP are caused by the configuration of the proxy server. The only modification to the application server is an AJP connector:

<Connector port="8009" protocol="AJP/1.3" />

Problems caused by incorrect proxy configuration

Unable to retrieve response

One application was not able to obtain the response from the other application. Examine the exception type for further context

java.io.EOFException

Typically, this is caused by content being encoded twice - once by the application, and then again by the reverse proxy. By default, Atlassian Applications have GZIP compression enabled.

Workaround

java.io.EOFException

Disable GZIP compression at the reverse proxy, or via the application configuration. E.g.

• Compressing an HTTP Response within Confluence
• Enabling GZIP compression - Bamboo
• Configuring Jira application options

Check your proxy configuration

Once your application server is configured correctly, it's important to ensure that your reverse proxy has been configured correctly. We recommend using the minimal configuration to ensure the reverse proxy works correctly before adding additional features such as load balancing and SSL. Refer to Proxying Atlassian Server Applications for more information.