[Other doc versions]
[Doc downloads]
This page explains how to establish a network topology in which Apache HTTP Server acts as a reverse proxy for Stash. Typically, such a configuration would be used when Stash is installed in a protected zone 'behind the firewall', and Apache HTTP Server provides a gateway through which users outside the firewall can access Stash. You may wish to do this if you want to:
Be aware that Stash does not need to run behind a web server, since it is capable of serving web requests directly; to secure Stash when run in this way see Securing Stash with Tomcat using SSL. For an overview of other network topology options, see Proxying and securing Stash. Otherwise, if you want to install Stash in an environment that incorporates Apache HTTP Server, this document is for you.
When Stash is set up following the instructions on this page, external access to Stash uses a reverse proxy, without using SSL. All communication between the user's browser and Apache, and so Stash, will be unsecured, but users do not have direct access to Stash.
On this page:
Note that:
This section has general information pertaining to the use of Apache HTTP Server and Apache Tomcat. It is important that you read this section before proceeding to the steps that follow.
The Stash distribution includes an instance of Tomcat 7, the configuration of which is determined by the contents of the
<Stash home directory>/shared/server.xml
file. Note that any changes that you make to the server.xml
file will only be effective upon starting or re-starting Stash.
You may find it helpful to refer to the Apache Tomcat 7.0 Proxy Support HowTo page.
Since Apache HTTP Server is not an Atlassian product, Atlassian does not guarantee to provide support for its configuration. You should consider the material on this page to be for your information only; use it at your own risk. If you encounter problems with configuring Apache HTTP Server, we recommend that you refer to the Apache HTTP Server Support page.
Note that Stash 2.10 and later versions do not support mod_auth_basic
.
You may find it helpful to refer to the Apache HTTP Server Documentation, which describes how you can control Apache HTTP Server by changing the contents of the httpd.conf
file. The section on Apache Module mod_proxy is particularly relevant. Note that any changes you make to the httpd.conf
file will only be effective upon starting or re-starting Apache HTTP Server.
Find the normal (non-SSL) Connector
directive in Tomcat's
<Stash home directory>/shared/server.xml
file, and add the scheme
, proxyName
, and proxyPort
attributes as shown below. Instead of mycompany.com
, set the proxyName
attribute to your domain name that Apache HTTP Server will be configured to serve. This informs Stash of the domain name and port of the requests that reach it via Apache HTTP Server, and is important to the correct operation of the Stash functions that construct URLs.
<Connector port="7990" protocol="HTTP/1.1" connectionTimeout="20000" useBodyEncodingForURI="true" redirectPort="8443" compression="on" compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript" scheme="http" proxyName="mycompany.com" proxyPort="80" />
Note: Apache HTTP Server's ProxyPreserveHost
directive is another way to have the hostname of the incoming request recognised by Stash instead of the hostname at which Stash is actually running. However, the ProxyPreserveHost
directive does not cause the scheme to be properly set. Since we have to mess with Tomcat's Connector
directive anyway, we recommend that you stick with the above-described approach, and don't bother to set the ProxyPreserveHost
in Apache HTTP Server.
For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 7.0 HTTP Connector Reference.
After re-starting Stash, open a browser window and log into Stash using an administrator account. Go to the Stash administration area and click Server settings (under 'Settings'), and change Base URL to match the proxy URL (the URL that Apache HTTP Server will be serving).
By default, Stash is configured to run with an empty context path; in other words, from the 'root' of the server's name space. In that default configuration, Stash is accessed at:
http://localhost:7990/
It's perfectly fine to run Stash with the empty context path as above. Alternatively, you can set a context path by changing the Context
directive in Tomcat's
<Stash home directory>/shared/server.xml
file:
<Context path="/stash" docBase="${catalina.home}/atlassian-stash" reloadable="false" useHttpOnly="true"> .... </Context>
If you do set a context path, it is important that the same path be used in Step 5, when setting up the ProxyPass
and ProxyPassReverse
directives. You should also append the context path to Stash's base URL (see Step 2).
mod_proxy
and mod_proxy_http
in Apache HTTP ServerIn the mod_proxy
documentation, you will read that mod_proxy
can be used as a forward proxy, or as a reverse proxy (gateway); you want the latter. Where the mod_proxy
documentation mentions 'origin server', it refers to your Stash server. Unless you have a good reason for doing otherwise, load mod_proxy
and mod_proxy_http
dynamically, using the LoadModule directive; that means un-commenting the following lines in the httpd.conf
file:
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Experienced administrators may be aware of the Apache Connector module, mod_jk
. Atlassian does not recommend use of the mod_jk
module with Stash, since it has proven itself to be less reliable than mod_proxy
.
mod_proxy
to map requests to StashTo configure mod_proxy
for use with Stash, you need to use the ProxyPass
and ProxyPassReverse
directives in Apache HTTP Server's httpd.conf
file as follows:
ProxyPass / http://localhost:7990/ connectiontimeout=5 timeout=300 ProxyPassReverse / http://localhost:7990/
Suppose Apache HTTP Server is configured to serve the mycompany.com
domain; then the above directives tell Apache HTTP Server to forward web requests of the form http://mycompany.com/*
to the Tomcat connector (Stash) running on port 7990
on the same machine.
The connectiontimeout
attribute specifies the number of seconds Apache HTTP Server waits for the creation of a connection to Stash.
The timeout
attribute specifies the number of seconds Apache HTTP Server waits for data to be sent to Stash.
If you set up a context path for Stash in Step 3, you'll need to use that context path in your ProxyPass
and ProxyPassReverse
directives. Suppose your context path is set to "/stash
", the directives would be as follows:
ProxyPass /stash http://localhost:7990/stash connectiontimeout=5 timeout=300 ProxyPassReverse /stash http://localhost:7990/stash
If Stash is to run on a different domain and/or different port, you should use that domain and/or port number in the ProxyPass
and ProxyPassReverse
directives; for example, suppose that Stash will run on port 9900
on private.mycompany.com
under the context path /stash
, then you would use the following directives:
ProxyPass /stash http://private.mycompany.com:9900/stash connectiontimeout=5 timeout=300 ProxyPassReverse /stash http://private.mycompany.com:9900/stash
mod_proxy
to disable forward proxyingIf you are using Apache HTTP Server as a reverse proxy only, and not as a forward proxy server, you should turn forward proxying off by including a ProxyRequests
directive in the httpd.conf
file, as follows:
ProxyRequests Off
Strictly speaking, this step is unnecessary because access to proxied resources is unrestricted by default. Nevertheless, we explicitly allow access to Stash from any host so that this policy will be applied regardless of any subsequent changes to access controls at the global level. Use the Proxy
directive in the httpd.conf
file as follows:
<Proxy *> Order Deny,Allow Allow from all </Proxy>
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 two contained directives to all proxied requests.
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 Stash via Apache HTTP Server. Here, we specify that all hosts are allowed access to Stash.
If you want to set up SSL access to Stash, follow the instructions on Securing Stash with Apache using SSL. When you are finished, users will be able to make secure connections to Apache HTTP Server; connections between Apache HTTP Server and Stash will remain unsecured (not using SSL). If you don't want to set up SSL access, you can skip this section entirely.
Note: It would be possible to set up an SSL connection between Apache HTTP Server and Tomcat (Stash), but that configuration is very unusual, and not recommended in most circumstances.
When an application link is established between Stash and another Atlassian product (for example JIRA), and Stash is operating behind Apache HTTP Server, the link from the other product to Stash must be via the proxy URL; that is, the 'reciprocal URL' from, say JIRA, to Stash must match the proxy name and port that you set at Step 1.
In general, if you are having problems:
LogLevel
directive in your httpd.conf
, and turn up logging (LogLevel debug
) to get more info.In particular:
/etc/selinux/config
) apparently fixes this.