How to configure an outbound HTTP and HTTPS proxy for Stash
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
The content on this page relates to platforms which are not supported. Consequently, Atlassian Support cannot guarantee providing any support for it. Please be aware that this material is provided for your information only and using it is done so at your own risk.
Purpose
This page defines how to configure Stash such that it can communicate externally through an outbound proxy. This is required to access servers outside the network it's hosted in, such as the Atlassian Marketplace. If you wish to host Stash behind a reverse-proxy (or inbound proxy), please refer to Proxying and securing Stash.
Configuration
Proxy Support is configured in Stash by passing certain system properties to the Java Virtual Machine (JVM) on startup. These properties follow the conventions defined by Oracle:
http.proxyHost
http.proxyPort
(default: 80)http.nonProxyHosts
(default: <none>)https.proxyHost
https.proxyPort
The http.proxyHost
property must be defined to configure an HTTP proxy, and https.proxyHost
for an HTTPS proxy. System property configuration is described in further detail within our Setting Properties and Options on Startup documentation.
The http.proxyHost
and http.proxyPort
properties indicate the proxy server and the port that the HTTP protocol handler will use. For example:
-Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.org -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts=localhost
The property http.nonProxyHosts
indicates the hosts which should be connected to directly and not through the proxy server. The value can be a list of hosts, each separated by a |, and in addition a wildcard character (*) can be used for matching. For example:
-Dhttp.nonProxyHosts=*.foo.com|localhost|confluence|crowd
The pipe character (|) may need to be escaped in Linux, as per our JAVA Option '-Dhttp.nonProxyHosts' Does Not Work KB article.
If the http.nonProxyHosts
property is not configured, all web requests will be routed through the proxy. For example, if connecting the Stash and JIRA applications together with Application Links, we would recommend bypassing the proxy and communicating on the internal network with this property. Routing through the proxy can have ramifications when taking into account IP validation on those links - the source IP of the server can be different depending on how the traffic is routed.
At the minimum, the http.nonProxyHosts must exclude localhost, otherwise certain functionality may not properly work. For example:
-Dhttp.nonProxyHosts=localhost
NTLM
NTLM is not supported by UPM. Please refer to
for further comments.It is not supported by Stash either: - STASH-7694Getting issue details... STATUS
It is not supported by JIRA either: - JRA-2398Getting issue details... STATUS
How to make it work with Stash, then?
As you can see from past comments: here and here, customers reported success by following the steps below:
- Install Cntlm Authentication Proxy locally to their JIRA/Stash server
Configured and tested it to make sure "Cntlm" works with their corporate NTLM and then used the parameters
- Have the configuration described on the section above point to the "Cntlm" proxy instead - and that one will do the job to talk to NTLM.
Application Links
If connecting Stash to any other applications, the application URL should be added to the nonProxyHosts
argument. Otherwise what can happen is when Stash attempts to talk to another Atlassian application the HTTP request can timeout, or not resolve. This will prevent the applications from linking. For example when connecting Stash to JIRA (located on jira.atlassian.com
):
-Dhttp.nonProxyHosts=localhost|*.atlassian.com
Configuring Authentication
Proxy authentication is configured by passing the below properties to Java:
http.proxyUser
http.proxyPassword
https.proxyUser
https.proxyPassword
Linux
Modify <Stash Installation>/bin/setenv.sh
and add the following to JVM_SUPPORT_RECOMMENDED_ARGS
:
JVM_SUPPORT_RECOMMENDED_ARGS="-Dhttp.proxyUser=atlaspirate -Dhttp.proxyPassword=yarrrrr -Dhttps.proxyUser=atlaspirate -Dhttps.proxyPassword=yarrrrr"
Windows
- Open the command window from
Start >> Run >> type in 'cmd' >> Enter
cd
to the bin directory of your STASH installation directoryRun:
tomcat8w //ES//AtlassianStash
- Click on the Java tab to see the list of current start-up options.
Add the proxy configuration options on their own lines under Java Options
-Dhttp.proxyUser=atlaspirate -Dhttp.proxyPassword=yarrrrr -Dhttps.proxyUser=atlaspirate -Dhttps.proxyPassword=yarrrrr
- Restart Stash