Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_ajp)

Starting from version 4.0, Fisheye has stopped support for the AJP authentication. For more information, see End of Support Announcements for Fisheye.

Atlassian applications allow the use of reverse-proxies with our products, however Atlassian Support does not provide assistance for configuring them. Consequently, Atlassian cannot guarantee providing any support for them.

If assistance with configuration is required, please raise a question on Atlassian Answers.

This page explains how to establish a network topology in which Apache HTTP Server acts as a reverse proxy for Atlassian server applications. The page has been written as a recipe for success – we recommend you follow it step by step. 

 You might consider using a reverse proxy when you want users to access the Atlassian applications: 

  • at their own domains, such as  http://our<atlassianapp>.com/
  • at subdomains of another domain, such as http://my<atlassianapp>.ourcompany.com/
  • at context paths on either a domain or subdomain, such as http://ourcompany.com/my<atlassianapp>
  • on different HTTP ports, such as 9800, 9850, etc.

For more complex scenarios, you can refer to the Apache HTTP Server documentation, consult with an Apache specialist in your organisation, ask a question on Atlassian Answers or contact one of our Atlassian Experts.

The instructions on this page apply to the following Atlassian server applications:

As of Bitbucket Server 5.0, it is not possible to configure AJP between your proxy and Tomcat server.

  • JIRA server applications (JIRA Software Server, JIRA Core, JIRA Service Desk)
  • Confluence Server (5.10 and earlier)
  • Bamboo Server
  • Bitbucket Server (4.14 and earlier)
  • Fisheye
  • Crucible
  • Crowd

In the examples that follow on this page, <atlassianapp> refers to the name of any of the Atlassian server applications above.

Atlassian server applications bundle a web server, which allows them to run without needing a proxy server. For most Atlassian applications, the bundled web server is Apache Tomcat (Fisheye and Crucible use Jetty). 

Consequently, you need to configure both Tomcat (or Jetty if using Fisheye or Crucible) and Apache HTTP Server when proxying an Atlassian application.

Prerequisites

You'll need the following:

Apache version 2.2 or 2.4 installed

You may find it helpful to refer to the Apache HTTP Server Documentation, which describes how you can control Apache HTTP Server by editing the httpd.conf file. The sections on Apache Module mod_proxy and Apache Module mod_ajp are particularly relevant. Note that any changes you make to the httpd.conf file will only be effective after restarting Apache HTTP Server.

DNS entries in place and configured for your domains

You should check, perhaps with your system or network administrator, whether the current DNS configuration for your organization will need changes to support the proxy topology you wish to set up.

The Atlassian applications installed, and accessible through a web browser

Install the Atlassian applications in the usual way.

 

Part A. Configure the Atlassian applications

This section describes how to configure the Tomcat (or Jetty) web server bundled with each Atlassian application to run behind a reverse proxy.

1. Stop the Atlassian applications

Stopping the application also stops Tomcat.

 

Click for stopping information...
JIRA applications

Use these commands from the JIRA installation directory:

  • bin/start-jira.sh
  • bin/stop-jira.sh

On Windows, use:

  • bin\start-jira.bat
  • bin\stop-jira.bat

See also JIRA application Startup and Shutdown Scripts.

Confluence

Use these commands from the Confluence installation directory:

  • bin/start-confluence.sh
  • bin/stop-confluence.sh

On Windows, use:

  • bin\start-confluence.bat
  • bin\stop-confluence.bat

See also Starting Confluence Automatically on System Startup.

Bamboo Server

Use these commands from the Bamboo installation directory:

  • bin/start-bamboo.sh
  • bin/stop-bamboo.sh

On Windows, use:

  • bin\start-bamboo.bat
  • bin\stop-bamboo.bat

See also Running Bamboo as a service.

Bitbucket Server

See Starting and stopping Bitbucket Server.

Fisheye

Use these commands from the Fisheye installation directory:

  • bin/start.sh
  • bin/stop.sh

On Windows, use:

  • bin\start.bat
  • bin\stop.bat

See also Running Fisheye as a Windows service.

Crucible

Use these commands from the Crucible installation directory:

  • bin/start.sh
  • bin/stop.sh

On Windows, use:

  • bin\start.bat
  • bin\stop.bat

See also Running Crucible as a Windows service.

Crowd

Use these commands from the Crowd installation directory:

  • /start_crowd.sh
  • /stop_crowd.sh

On Windows, use:

  • \start-crowd.bat
  • \stop-crowd.bat

See also Installing Crowd as a Windows Service.

2. Set the context path

This step is only required if you want an application to be accessed on a context path, such as http://ourcompany.com/<contextpath>. If this is not required, you can skip this step.

Fisheye and Crucible

If you're proxying Fisheye or Crucible, configure the web context path for Jetty from the admin area. See Configuring the Fisheye web server.

JIRA applications, Confluence, Bitbucket Server, Bamboo

If you're proxying any of these Atlassian server applications, configure the context path in the Tomcat server.xml file as follows.

 

Click for server.xml location info...

The location of your server.xml file depends on your application, operating system, and installation location. 

Common default installation locations for Atlassian applications are:

  • Linux: /opt/atlassian/<application-name>
  • Windows: C:\Program Files\Atlassian\<application-name>
  • Windows: C:\Atlassian\<application-name>

Locations in Atlassian application's folder structure:

Application server.xml location
Bamboo <install-path>/conf/
Confluence <install-path>/conf/
Crowd <install-path>/apache-tomcat/conf/
Crucible As for Fisheye.
Fisheye The Fisheye configuration file is config.xml, see Configuring the Fisheye web server and How to enable Fisheye/Crucible to listen to web requests on additional ports.
JIRA applications <install-path>/conf/
Bitbucket Server 5.0

N/A, replaced by <Bitbucket home directory>/shared/bitbucket.properties

Please read through Migrate server.xml customizations to bitbucket.properties

Bitbucket Server 4.0 – 4.14 <Bitbucket home directory> /shared/server.xml
Stash 3.8 – 3.11

<Stash home directory>/shared/

If you are on any of these later releases but your server.xml does not exist in the directory above, it means that you are running from the <install-path>/conf/server.xml.

We recommend that you copy <install-path>/conf/server.xml into <Stash home directory>/shared/ that way you won't need to worry about this when you upgrade your instance.


Stash 3.7 and earlier <install-path>/conf/

<install-path> refers to where the application was installed on your system.

 

If you are configuring Bitbucket Server 5.0

As of Bitbucket Server 5.0, you can't configure any Tomcat connectors directly, therefore the configurations in this section only apply for Bitbucket server 4.14 or earlier.

server.xml configurations have been replaced by <Bitbucket home directory>/shared/bitbucket.properties

Please read through Moving Bitbucket Server to a different context path for Bitbucket Server 5.0 and later specific instructions.

 

 

In the Tomcat server.xml configuration file for all applications except Crowd, locate the Context directive that looks like this:

<Context path="" docBase="${catalina.home}/atlassian-<atlassianapp>" reloadable="false" useHttpOnly="true">

Change the directive to add the new context path:

<Context path="/<contextpath>" docBase="${catalina.home}/atlassian-<atlassianapp>" reloadable="false" useHttpOnly="true">

Use your own value for <contextpath>. Typically, each application would use a different context path.

It is important that the path value has a leading forward slash (/) like path="/<contextpath>" rather than path="<contextpath>".

Use these instructions to Removing the 'crowd' Context from the Application URL.

3. Configure the Connector directive

Fisheye and Crucible

If you're proxying Fisheye or Crucible, you must set the AJP Bind Address per Fisheye instance fr

om the admin area. See  Configuring the Fisheye web server.

JIRA applications, Confluence, Bitbucket Server, Bamboo

If you're using any of the other Atlassian server applications, you will need to enable the AJP Connector on the Tomcat container by uncommenting a line similar to the following:

<Connector port="8009" URIEncoding="UTF-8" enableLookups="false" protocol="AJP/1.3" />

If that doesn't exist in your server.xml configuration, you'll need to add the element yourself, following the eample above. You can choose a port of your liking and configure it as described on Changing port that your Atlassian application listens on.

Please keep in mind that we have the the port 8009 commented out in a few of the server.xml we ship on different applications. If you are running multiple applications on the same server they'll need to have their ports changed to a different value, otherwise you will have a port conflict.

Part B. Configure Apache HTTP Server

1. Enable the mod_proxy_ajp modules in Apache

The preferred configuration is Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http). This works with any application server, and together with mod_proxy_html allows complex URL rewriting to deal with different application paths on the web server and the application server.

In addition, note that mod_jk and mod_jk2 are other commonly used AJP modules and not covered by this documentation.

 

 

Expand to see Debian/Ubuntu instructions
  1. Enable the module with the following:

    $ sudo a2enmod proxy_ajp
    Considering dependency proxy for proxy_ajp:
    Module proxy already enabled
    Enabling module proxy_ajp.
    To activate the new configuration, you need to run:
    service apache2 restart
  2. Restart Apache.
Expand to see Fedora and CentOS instructions

Fedora and CentOS 7 refer to Apache as 'httpd' and enable the mod_proxy_ajp_proxy modules by default. If necessary, you can find the configuration files in the /etc/httpd/conf/, /etc/httpd/conf.d/ and /etc/httpd/conf.modules.d/ directories.

For more information about how the configuration files are processed, see:

Expand to see Windows/Other OS instructions
  1. Locate and edit the httpd.conf file, adding the below lines:

    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
  2. Restart Apache.

2. Configure the virtual hosts using mod_proxy_ajp

More information can be found on Apache Module mod_proxy_ajp.

  • Note that for CentOS, the preferred approach is to add the virtual host block to a separate configuration file for each application in /etc/httpd/conf.d/, for example named confluence-vhost.conf and jira-vhost.conf
  • Note that for Debian, the preferred approach is to add the virtual host block to a separate configuration file for each application in  /etc/apache2/sites-available/<site>, for example named confluence.conf and/or jira.conf. These should be based on the default template, 000-default.con.


The example below is for one single application running behind a reverse proxy configured with Name-Based Virtual Hosts:

<VirtualHost *:80>
    ServerName <subdomain>.<domain>.com
     
    ProxyRequests Off
    
    <Proxy *>
         Require all granted
    </Proxy>
 
    ProxyPass /<contextpath> ajp://<domain>:<port>/<contextpath>
    ProxyPassReverse /<contextpath> ajp://<domain>:<port>/<contextpath>
</VirtualHost>

If you have multiple applications running behind the same proxy, you can configure the following ways using Name-Based Virtual Hosts:

  • Use a single Name-Based Virtual Host if the Atlassian applications are under the same domain but different context paths. For example:

    <VirtualHost *:80>
        ServerName mycompany.com
         
        ProxyRequests Off
         
        <Proxy *>
             Require all granted
        </Proxy>
     
        ProxyPass /jira ajp://mycompany.com:8080/jira
        ProxyPassReverse /jira ajp://mycompany.com:8080/jira
     
        ProxyPass /bitbucket ajp://mycompany.com:7990/bitbucket
        ProxyPassReverse /bitbucket ajp://mycompany.com:7990/bitbucket
    </VirtualHost>
  • Use multiple Name-Based Virtual Hosts if each application is on a different domain:

    <VirtualHost *:80>
        ServerName myjira.com
         
        ProxyRequests Off
         
        <Proxy *>
             Require all granted
        </Proxy>
     
        ProxyPass /jira ajp://myjira.com:8080/jira
        ProxyPassReverse /jira ajp://myjira.com:8080/jira
     
    </VirtualHost>
     
    <VirtualHost *:80>
        ServerName mybitbucket.com
         
        ProxyRequests Off
         
        <Proxy *>
             Require all granted
        </Proxy>
     
        ProxyPass /bitbucket ajp://mybitbucket.com:7990/bitbucket
        ProxyPassReverse /bitbucket ajp://mybitbucket.com:7990/bitbucket
    </VirtualHost>


For more information about virtual hosts see https://httpd.apache.org/docs/2.4/vhosts/.

The directives inside the virtual host block perform these functions:

Directive Function


<VirtualHost *:80>


Configure directives for a particular virtual host

Use the character * as a wildcard to match all IP addresses, with the default port of 80. This causes Apache to match requests on the ServerName values of the virtual hosts.

See the Apache 2.4 VirtualHost documentation.


ServerName <subdomain>.<domain>.com


Identify the server

The ServerName directive can be used to set the request scheme, hostname and port that the server uses to identify itself.

Examples:

The ServerName directive should not include the context path.

See the Apache 2.4 ServerName documentation.


ProxyRequests Off
Turn off forward proxying

This directive tells Apache to turn off forward proxying. You only need to include this directive if you are using Apache HTTP Server as just a reverse proxy, and not as a forward proxy server.

See the Apache 2.4 ProxyRequests documentation.


<Proxy *>
 Require all granted
</Proxy>


Allow proxying to the Atlassian application from everywhere

Strictly speaking, this step is unnecessary because access to proxied resources is unrestricted by default. Nevertheless, we explicitly allow access to the Atlassian application from any host so that this policy will be applied regardless of any subsequent changes to access controls at the global level. The Proxy directive provides a context for the directives that are contained within its delimiting tags. In this case, we specify a wild-card URL (the asterisk), which applies the contained directive to all proxied requests.

See the Apache 2.4 Proxy directive documentation.

Note that for Apache 2.2, you need to use the following instead:

<Proxy *>
    Order Deny,Allow
    Allow from all
</Proxy>

The Order directive controls the order in which any Allow and Deny directives are applied. In the above configuration, we specify "Deny,Allow", which tells Apache HTTP Server to apply any Deny directives first, and if any match, the request is denied unless it also matches an Allow directive. In fact, "Deny,Allow" is the default; we include it merely for the sake of clarity. Note that we specify one Allow directive, which is described below, and don't specify any Deny directives. The Allow directive, in this context, controls which hosts can access the Atlassian application via Apache HTTP Server. Here, we specify that all hosts are allowed access.

See the Apache 2.2 Proxy directive documentation.


ProxyPass /<contextpath> ajp://<domain>:<port>/<contextpath>

ProxyPassReverse /<contextpath> ajp://<domain>:<port>/<contextpath>


These directives tell Apache HTTP Server to forward requests of the form  http://example.com/*  to port 8080 on the same machine, which is the port we configured Tomcat to listen on above.

The example below shows how to use the context path ( /<atlassianapp>described above with mod_proxy. If you're not using a context path, you can omit that from your ProxyPass and ProxyPassReverse directives: 

ProxyPass /<contextpath> ajp://<domain>:<port>/<contextpath>
ProxyPassReverse /<contextpath> ajp://<domain>:<port>/<contextpath>

Append a '/' after the domain name or port.

The example below shows how to access the application at the  private.example.com  subdomain, with the context path /<atlassianapp>, and connecting to Tomcat on port 9900:

ProxyPass        /<atlassianapp> ajp://private.example.com:9900/<atlassianapp>
ProxyPassReverse /<atlassianapp> ajp://private.example.com:9900/<atlassianapp>

Don't use a trailing '/' after a context path.Note that you could use localhost instead of <domain> if you are running the Atlassian application on the same machine as Apache.

See the Apache 2.4  ProxyPass and  ProxyPassReverse  directives documentation.


3. Restart Apache

Debian and Ubuntu

Restart Apache from the command line using:

$ sudo service apache2 restart

Fedora and CentOS

Restart Apache from the command line using:

$ sudo apachectl graceful

You can also use systemd to restart Apache. On CentOS, for example, use:

$ sudo systemctl restart httpd.service

Windows

You can stop and start the Apache service by going to Control Panel > Administrative Tools > Services , look for "Apache2" and select it. Now, on the menu bar select the stop button (square) and wait for the status of the service to change to 'Stopped'. Once the service has stopped select the start button (triangle) and wait for the status to change to 'Started'.

4. Modify the CentOS SELinux policy

For CentOS, the SELinux policy blocks httpd from connecting with the network by default. In this case you'll see a "permission denied" message in the  httpd error_log similar to this:

[Sat Mar 19 00:29:45.722758 2016] [proxy:error] [pid 5958] (13)Permission denied: AH00957: HTTP: attempt to connect to 127.0.0.1:8090 (localhost) failed

You need to manually modify the SELinux policy for the httpd process using the following command:

$ sudo /usr/sbin/setsebool -P httpd_can_network_connect 1

Part C. Final configuration

Restart each application

Now, restart each application and ensure you can access them using new URLs. See the stopping and starting instructions above.

Set the application Base URL

For each Atlassian application, set the Base URL to the address you configured in the proxy, which is the URL that Apache HTTP Server will be serving (such as http://www.example.com/<atlassianapp>).

Last modified on Oct 11, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.