How to configure an outbound HTTP and HTTPS proxy for Bitbucket Server

Still need help?

The Atlassian Community is here for you.

Ask the community

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.

Section 1: Purpose

This page defines how to configure Bitbucket Server 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 Bitbucket Server behind a reverse-proxy (or inbound proxy), please refer to Proxy and secure Bitbucket.

Section 2: Configuration

Proxy Support is configured in Bitbucket Server 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 Configuration Properties 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
tip/resting Created with Sketch.

As of Bitbucket Server 5.0+ the following notes apply:

  • a pipe (|) does not need to be escaped with the backslash (\). Using the pipe(|) alone is sufficient for multiple proxy hosts.
  • when defining multiple proxy hosts, don't use the quotes (") or the escaped quotes (\") to wrap the various values. Simply specify the attributes as a pipe-separated list.

For a Bitbucket version older than 5.0, the pipe character (|) may need to be escaped in Linux. (Ref: JAVA Option '-Dhttp.nonProxyHosts' Does Not Work).


If the http.nonProxyHosts property is not configured, all web requests will be routed through the proxy. That said, when connecting two Atlassian Applications such as a Bitbucket Server instance and a Jira server instance together via Application Links, we would recommend bypassing the proxy and adding the latter http.nonProxyHosts property (Please check Additional Point #2 below).

Note that 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. So we would have:

-Dhttp.nonProxyHosts=localhost

Additional Point 1: NTLM

NTLM is:

  •  not supported by UPM. (Please refer to the following report  Unable to locate Jira server for this macro. It may be due to Application Link configuration.  for further details).
  • It is not supported by Stash either:  STASH-7694 - Getting issue details... STATUS
  • It is not supported by JIRA either:  JRA-2398 - Getting 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:

1. Install Cntlm Authentication Proxy locally to their JIRA/Stash server

2. Configured and tested it to make sure "Cntlm" works with their corporate NTLM and then used the parameters

3. Update your user, domain, and proxy information in cntlm.ini, then test your proxy with this command (run in your Cntlm installation folder):

cntlm -c cntlm.ini -I -M http://google.ro

4. It will ask for your password, and hopefully print your required authentication information, which must be saved in your cntlm.ini


Sample cntlm.ini:
Username            user
Domain              domain

# provide actual value if autodetection fails
# Workstation         pc-name

Proxy               my_proxy_server.com:80
NoProxy             127.0.0.*, 192.168.*

Listen              127.0.0.1:54321
Listen              192.168.1.42:8080
Gateway             no

SOCKS5Proxy         5000
# provide socks auth info if you want it
# SOCKS5User          socks-user:socks-password

# printed authentication info from the previous step
Auth            NTLMv2
PassNTLMv2      98D6986BCFA9886E41698C1686B58A09

Note: on linux the config file is cntlm.conf

5. Have the configuration described on the section above point to the "Cntlm" proxy instead - and that one will do the job to communicate with NTLM.


If connecting Bitbucket Server to any other applications, the application URL should be added to the nonProxyHosts argument. Otherwise what can happen is when Bitbucket Server 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 Bitbucket Server to JIRA (located on  jira.atlassian.com ):

-Dhttp.nonProxyHosts=localhost|*.atlassian.com

Additional Point 3: Repository Importer

Starting with Bitbucket Server 4.9, it's possible to import git repositories directly. This does not use Java, but instead native Git. The proxy configuration made will not apply. Instead, you will also need to configure http.proxy for the Git client as mentioned in https://git-scm.com/docs/git-config.

Additional Point 4: Configuring Authentication

Proxy authentication is configured by providing the below properties to Java:

  • http.proxyUser
  • http.proxyPassword
  • https.proxyUser
  • https.proxyPassword

For Bitbucket Server 5.0+

setenv and environment variable changes in Bitbucket Server 5.0+

Starting with Bitbucket Server 5.0, setenv.sh and setenv.bat have been removed. The options that were set in this file can now be set via environment variables. Where to set the environment variable depends on which Operating System you're running on.

Linux

When using the atlbitbucket service on Linux, the environment variables are ignored.

For Bitbucket Server 5.0+, you should set the parameters in _start-webapp.sh. These values will be read when the service starts.

As an example, to set JVM_SUPPORT_RECOMMENDED_ARGS, you would add this line to the file:

JVM_SUPPORT_RECOMMENDED_ARGS="-Dhttp.proxyUser=atlaspirate -Dhttp.proxyPassword=yarrrrr -Dhttps.proxyUser=atlaspirate -Dhttps.proxyPassword=yarrrrr"
Windows

Set the parameter as an environment variable for the user running Bitbucket Server. For example, if you want to set JVM_SUPPORT_RECOMMENDED_ARGS, create it as an environment variable and assign the appropriate value to it. When Bitbucket Server starts using the startup scripts or service, it will pick up and apply this value.

For Older Bitbucket Server versions: 

Linux

For older Bitbucket Server versions, the script file to modify is <Bitbucket Server Installation>/bin/setenv.sh, an example would be:

JVM_SUPPORT_RECOMMENDED_ARGS="-Dhttp.proxyUser=atlaspirate -Dhttp.proxyPassword=yarrrrr -Dhttps.proxyUser=atlaspirate -Dhttps.proxyPassword=yarrrrr"
Windows
  1. Open the command window from Start >> Run >> type in 'cmd' >> Enter
  2. cd to the bin directory of your Bitbucket Server installation directory
  3. Run ONE of the following commands:
    For Bitbucket Server up to version 4.14.5

    tomcat8w.exe //ES//%SERVICENAME%


    For Bitbucket Server version 5.0+

    bservmgr.exe //ES/%SERVICENAME%

    Replace %SERVICENAME% with the name of your actual service name, as AtlassianBitbucket.

  4. Click on the Java tab to see the list of current start-up options.
  5. Add the proxy configuration options on their own lines under Java Options 

    -Dhttp.proxyUser=atlaspirate 
    -Dhttp.proxyPassword=yarrrrr 
    -Dhttps.proxyUser=atlaspirate 
    -Dhttps.proxyPassword=yarrrrr
  6. Restart Bitbucket Server


Description

This page defines how to configure Bitbucket Server such that it can communicate externally through an outbound proxy.


ProductBitbucket



Last modified on May 11, 2022

Was this helpful?

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