Securing Stash behind HAProxy using SSL
- Stash is installed in a protected zone 'behind the firewall', and HAProxy provides a gateway through which users outside the firewall can access Stash.
- Stash needs to be served on protected ports (e.g. ports < 1024 on Linux). Stash cannot access these ports directly as it must not be run as a privileged user (e.g root). In this case HAProxy can bind to these ports and forward the requests to Stash.
On this page:
The configuration described on this page results in a scenario where:
- External client connections with HAProxy are secured using SSL. Connections between HAProxy and Stash are unsecured.
- Stash and HAProxy run on the same machine.
- Stash is currently available at
- Stash is to be made available at
Please note that:
- We assume that you already have a running instance of HAProxy.
- SSL certificates must be installed on the server machine.
- Any existing links with other applications will need to be reconfigured using the new URL for Stash.
- Securing Git operations between the user's computer and Stash is a separate consideration - see Enabling SSH access to Git.
- It is also possible to get Stash to directly use SSL without the help of a proxy as documented in Securing Stash with Tomcat using SSL.
Note that the Atlassian Support Offering does not cover HAProxy integration, but you can get assistance with HAProxy from the Atlassian community on answers.atlassian.com, or from an Atlassian Expert.
Step 1: Set a context path for Stash
Stash and HAProxy need to be serving from the same context. Stash is currently accessed at http://mycompany.com:7990. It needs to be changed to serve from
http://mycompany.com:7990/stash to match context
<Stash home directory>/shared/server.xml file, set the context path to
- If you use a context path, it is important that the same path is appended to the context path of Stash's base URL (Step 2).
- The context path for serving from the root context is
Step 2: Change Stash's base URL
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 URL HAProxy will be serving. For this example, use
Step 3: Configure the Tomcat Connector
Find the normal (non-SSL)
Connector directive in Tomcat's
<Stash home directory>/shared/server.xml file, and add the
redirectPort attributes. These attributes tell Tomcat how HAProxy is serving Stash so it can generate correct URLs. Following our example:
proxyPortis set to 443 to indicate that HAProxy is accepting connections over on the standard HTTPS port 443.
schemeare are set to the values that HAProxy is serving Stash over.
secureattribute is also set to
trueto tell Stash that the connection between the client and HAProxy is considered secure.
redirectPortis set to 443 so that Tomcat knows how to send a user to a secure location when necessary (this is not really necessary in this example because this connector is already
For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 7.0 HTTP Connector Reference.
Step 4: Configure HAProxy
Merge the example below into your HAProxy configuration (e.g
/etc/haproxy/haproxy.cfg). This is a complete HAProxy 1.5.x configuration. Note that HAProxy 1.5.x or greater is required for SSL support. You can just take the bits that fit your needs. The important configuration is in the
(Optional) Step 4: Redirect SSH connections
HAProxy also has the ability to proxy all Stash SSH traffic. See Setting up SSH port forwarding for details.
Here are some resources you may find helpful in setting up Stash behind HAProxy:
Was this helpful?
Thanks for your feedback!