# Stash Latest : Integrating Stash with Apache HTTP Server

This page last changed on May 08, 2012 by dpinn.

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. 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 HTTPS. Otherwise, if you want to install Stash in an environment that incorporates Apache HTTP Server, this document is for you. ## About using Apache software 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. ### Configuring Tomcat 6 The Stash distribution includes an instance of Tomcat 6, the configuration of which is determined by the contents of the `server.xml` file, which can be found in the `conf` directory immediately under the Stash installation directory. Note that any changes that you make to the `server.xml` file will be effective upon starting or re-starting Stash. You may find it helpful to refer to the Apache Tomcat 6.0 Proxy Support HowTo page. | On this page: About using Apache software Step 1: Configure the Tomcat Connector Step 2: Change Stash's base URL Step 3 (optional): Set a context path for Stash Step 4: Enable `mod_proxy` and `mod_proxy_http` in Apache HTTP Server Step 5: Configure `mod_proxy` to map requests to Stash Step 6: Configure `mod_proxy` to disable forward proxying Step 7: Allow proxying to Stash from everywhere Step 8 (optional): Configure Apache HTTP Server for SSL A note about application links Troubleshooting Related pages: Securing Stash with HTTPS

### Configuring Apache HTTP Server

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.

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 be effective upon starting or re-starting Apache HTTP Server.

This document relates to Apache HTTP Server version 2.4.2; the configuration of other versions may differ.

## Step 1: Configure the Tomcat Connector

Find the normal (non-SSL) `Connector` directive in Tomcat's `server.xml` file, and add the `scheme` , `proxyName` , and `proxyPort` attributes as shown below. Instead of `mycompany.com`, set the `proxyName` attribute to the 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 URL's.

    <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 6.0 HTTP Connector Reference.

## Step 2: Change Stash's base URL

After re-starting Stash, open a browser window and log into Stash using an administrator account. Visit Administration > Settings > General Settings, and change the base URL to match the proxy URL (the URL that Apache HTTP Server will be serving).

## Step 3 (optional): Set a context path for Stash

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 `server.xml` file:

    <Context path="/stash" docBase="${catalina.home}/atlassian-stash.war" 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).

## Step 4: Enable `mod_proxy` and `mod_proxy_http` in Apache HTTP Server

In 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`.

## Step 5: Configure `mod_proxy` to map requests to Stash

To 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

## Step 6: Configure `mod_proxy` to disable forward proxying

If 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

## Step 7: Allow proxying to Stash from everywhere

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.

## Step 8 (optional): Configure Apache HTTP Server for SSL

If you want to set up SSL access to Stash, take steps 7(a) to 7(d) below. 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.

### Step 8(a): Configure the Tomcat Connector for SSL

Find the normal (non-SSL) `Connector` directive in Tomcat's `server.xml` file, and change the `redirectPort` , `scheme` and `proxyPort` attributes as follows:

    <Connector port="7990"
    protocol="HTTP/1.1"
    connectionTimeout="20000"
    useBodyEncodingForURI="true"
    redirectPort="443"
    compression="on"
    compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript"
    secure="true"
    scheme="https"
    proxyName="mycompany.com"
    proxyPort="443" />

The `redirectPort` directive causes Tomcat-initiated redirections to secured resources to use the specified port. Right now, the Stash configuration of Tomcat does not involve Tomcat-initiated redirections, so the change to `redirectPort` is redundant. Nevertheless, we suggest that you change it as directed above for the sake of completeness.

### Step 8(b): Set up a virtual host in Apache HTTP Server

Un-comment the following LoadModule directive in Apache HTTP Server's `httpd.conf` file:

    LoadModule ssl_module modules/mod_ssl.so

Add the following directives to the `httpd.conf` file:

    Listen 443
    <VirtualHost *:443>
    SSLEngine On
    SSLCertificateFile    "/usr/local/apache2/conf/server.crt"
    SSLCertificateKeyFile "/usr/local/apache2/conf/server.key"
    ProxyPass        / http://localhost:7990/ connectiontimeout=5 timeout=300
    ProxyPassReverse / http://localhost:7990/
    </VirtualHost>

The `Listen` directive instructs Apache HTTP Server to listen for incoming requests on port 443. Actually, we could omit that directive in this case, since Apache HTTP Server listens for `https` requests on port 443 by default. Nevertheless, it's good to make one's intentions explicit.

The `VirtualHost` directive encloses a number of child directives that apply only and always to requests that arrive at port 443. Since our `VirtualHost` block does not include a `ServerName` directive, it inherits the server name from the main server configuration.

The `SSLEngine` directive toggles the use of the SSL/TLS Protocol Engine. In this case, we're using it to turn SSL on for all requests that arrive at port 443.

The `SSLCertificateFile` directive tells Apache HTTP Server where to find the PEM-encoded certificate file for the server.

The `SSLCertificateKeyFile` directive tells Apache HTTP Server where to find the PEM-encoded private key file corresponding to the certificate file identified by the `SSLCertificateFile` directive. Depending on how the certificate file was generated, it may contain a RSA or DSA private key file, making the `SSLCertificateKeyFile` directive redundant; however, Apache strongly discourages that practice. The recommended approach is to separate the certificate and the private key. If the private key is encrypted, Apache HTTP Server will require a pass phrase to be entered when it starts up.

The `ProxyPass` and `ProxyPassReverse` directives should be set up in manner described in Step 5.

For more information about the support for SSL in Apache HTTP Server, refer to the Apache SSL/TLS Encryption manual. In addition, you will find lots of relevant information in the `<apache directory>/conf/extra/httpd-ssl.conf` file, which is included in the standard Apache distribution.

### Step 8(c): Create SSL certificate and key files

In Step 8(b), you specified `server.crt` and `server.key` as the certificate file and private key file respectively. Those two files must be created before we can proceed. This step assumes that OpenSSL is installed on your server.

Generate a server key file:

    openssl genrsa -des3 -out server.key 1024

You will be asked to provide a password. Make sure that the password is strong because it will form the one real entry point into the SSL encryption set-up. Make a note of the password because you'll need it when starting Apache HTTP Server later.

Generate a certificate request file (`server.csr`):

    openssl req -new -key server.key -out server.csr

Generate a self-signed certificate (`server.crt`):

    openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

The above command generates a self-signed certificate that is valid for one year. You can use the certificate signing request to purchase a certificate from a certificate authority. For testing purposes though, the self-signed certificate will suffice. Copy the certificate file and private key file to the locations you specified in Step 8(b).

    cp server.key /usr/local/apache2/conf/
    cp server.crt /usr/local/apache2/conf/

### Step 8(d): Update the base URL for 'https'

Open a browser window and log into Stash using an administrator account. Visit Administration > Settings > General Settings, and change the base URL use 'https'.

### Using a self-signed certificate

There are two implications of using the self-signed certificate:

- When you access Stash in a web browser, you can expect a warning to appear, alerting you that an un-trusted certificate is in use. Before proceeding you will have to indicate to the browser that you trust the certificate.
- When you perform a git clone operation, SSL verification will fail.

The SSL verification error message will look something like this:

`error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed while accessing https://justme@mycompany/git/TP/test.git`

It's easy to fix. Turn SSL verification off for individual git operations by setting the `GIT_SSL_NO_VERIFY` environment variable. In Unix, you can set the variable in-line with git commands as follows:

`GIT_SSL_NO_VERIFY=true git clone https://justme@mycompany/git/TP/test.git`

In Windows you have to set the variable in a separate shell statement:
`set GIT_SSL_NO_VERIFY=true`
`git clone https://justme@mycompany/git/TP/test.git`
Once you have purchased and installed a signed certificate from a certificate authority, you will no longer have to include the `GIT_SSL_NO_VERIFY` modifier.

## A note about application links

When an application link is established between Stash and another Atlassian product (e.g. 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 comport with the proxy name and port that you set at Step 1.

## Troubleshooting

- On Fedora Core 4, people have reported 'permission denied' errors when trying to get mod_proxy (and mod_jk) working. Disabling SELinux (`/etc/selinux/config`) apparently fixes this.
- Some users have reported problems with user sessions being hijacked when the mod_cache module is enabled. If you have such problems, disable the mod_cache module. Note that this module is enabled by default in some Apache HTTP Server version 2 distributions.
- In general, if you are having problems:

- 1. Ensure that Stash works as expected when running directly from Tomcat on http://localhost:7990/stash.
  2. Watch the log files (usually in /var/log/httpd/ or /var/log/apache2/). Check that you have a LogLevel directive in your httpd.conf, and turn up logging ('LogLevel debug') to get more info.
  3. Check out the Stash Knowledge Base.