Migrate server.xml customizations to bitbucket.properties

On this page

Bitbucket Server 5.0 introduces some changes to how connector configuration customisation is performed. In Bitbucket Server 4.x and earlier Bitbucket Server startup involved starting Apache Tomcat and deploying the web application into Tomcat. Customising connector configuration (for example to secure connections with SSL) involved updating the Tomcat server.xml file.

In Bitbucket Server 5.0 and later, an embedded container (still Apache Tomcat) is started by the application. This allows you to make customizations to connector configuration directly in the bitbucket.properties file (the same file that hosts the vast majority of other settings).

Upgrading from any version earlier than Bitbucket Server 4.14 or earlier to Bitbucket Server 5.x or later requires that you manually migrate any changes to the server.xml file to the bitbucket.properties file.

This document explains in what cases this may be necessary, describes how to perform this migration, and provides some migration examples for common use cases.

How do I know if there were customizations to my server.xml file?

The server.xml file was where you would make customizations to do a number of things, but most users used it to:

  • Secure Bitbucket Server using SSL.
  • Run Bitbucket Server behind a reverse proxy.
  • Changed the port Bitbucket Server runs on.
  • Set up a custom keystore.

How to migrate your customizations to bitbucket.properties

To migrate customizations made in the server.xml file to the bitbucket.properties file

 
  1. Locate your server.xml file.
     

    Tell me where to look...
    Release Directory
    Stash 3.7 and earlier <Stash installation directory>/conf/server.xml
    Stash 3.8 and later <Stash home directory>/shared/server.xml
    Bitbucket Server 4.0 - 4.14 <Bitbucket home directory>/shared/server.xml
    Bitbucket Server 5.0 and later N/A, replaced by <Bitbucket home directory>/shared/bitbucket.properties
  2. Identify and note any customizations made. Ideally you will know which customizations were made and can locate them in your server.xml file.
     

    Here are some common customizations...

    This is not a comprehensive list. Review your server.xml file closely to ensure all your customizations are noted.

    1. Securing Bitbucket using SSL.

    2. Running Bitbucket behind a reverse a proxy.
    3. Bypassing the Bitbucket reverse proxy to solve Application Links issues.
    4. Bypassing the Bitbucket proxy to connect directly to a Data Center node (for troubleshooting, or to generate support zips).
    5. Configuring a custom keystore path and password.
  3. Locate your bitbucket.properties file in the <Bitbucket home directory> /shared directory.

  4. Look up the customization equivalent in the bitbucket.properties file by referring to one of the migration examples and/or by using the migration table below.

  5. Add the equivalent values to the bitbucket.properties file. Save and close the file.

    For Bitbucket Data Center users...

    The value for your load balancer to support session affinity ("sticky sessions") was previously set to JSESSIONID. The default value for Bitbucket 5.0+ has changed to BITBUCKETSESSIONID.

    You need to either change your load balancer cookie configuration to BITBUCKETSESSIONID, or, change the value in the bitbucket.properties file to JSESSIONID.


    To change the value in the bitbucket.properties file, add this line

    server.session.cookie.name=JSESSIONID

     

    To change this value in your load balancer configuration, locate your load balancer proxy configuration file, change the instances of JSESSIONID to BITBUCKETSESSIONID.

     

  6. Remove or rename the server.xml file (don't delete this file until you confirm the customizations were successfully migrated to your upgraded instance). 

Migration reference table

Show me the table...
4.x and earlier (server.xml) 5.x and later (bitbucket.properties)
compression="on" server.compression.enabled=true
compressableMimeType=
"text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript"
server.compression.mime-types=
text/css,text/html,text/javascript,text/json,text/plain,text/xml,text/x-javascript,\
  application/javascript,application/json,application/x-javascript,application/vnd.git-lfs+json
connectionTimeout="20000" server.connection-timeout=20000
path="/" server.context-path=/
N/A server.displayName=Atlassian Bitbucket
port="7990" server.port=7990
useHttpOnly="true" server.session.cookie.http-only=true
secure="true" server.secure=true
SSLEnabled="true" server.ssl.enabled=true
keyAlias="YourAlias"

certificateKeyAlias="YourAlias"

server.ssl.key-alias=tomcat
keystoreFile="/path/to/keystore/bitbucket.jks"

certificateKeystoreFile="/path/to/keystore/bitbucket.jks"

server.ssl.key-store=${bitbucket.shared.home}/config/ssl-keystore

keystorePass="<password value>"

certificateKeystorePassword="<password value>"

server.ssl.key-store-password=changeit
sslProtocol="TLSv1.2" server.ssl.protocol=TLSv1.2
keystoreType="JKS"

certificateKeystoreType="JKS"

server.ssl.key-store-type=${keystore.type:jks}

clientAuth="false" or clientAuth="true"

server.ssl.client-auth=want or server.ssl.client-auth=need
redirectPort="443" server.redirect-port=443
proxyPort="443" server.proxy-port=443
proxyName="mycompany.com" server.proxy-name=mycompany.com
address="192.168.10.10" server.address=192.168.10.10

 

For Bitbucket Data Center

These properties are applicable to Bitbucket Data Center instances. In previous versions these were set within load balancer configuration files. Depending on which load balancer you're using, there are many configuration options, so it is not possible to precisely describe the properties or values for every configuration.

Setting these values within the bitbucket.properties in file in 5.0+ overrides what's in the load balancer configuration file.

  • server.session.cookie.name=BITBUCKETSESSIONID
  • server.session.timeout=1800
  • server.session.tracking-modes=cookie

 


 

Migration examples

Below are some examples that demonstrate some common use cases for customizing the server.xml file, and how you would migrate those values to the bitbucket.properties file.

For these examples, if there are less properties in the bitbucket.properties syntax then in the initial server.xml syntax, that indicates the default value would be acceptable and you don't need to add that property to achieve the same result.

Read the Bitbucket Server config properties - Server section for more details about all of the various properties that can be configured.

For Windows users

When adding values with file paths in them, for instance server.context-path, backslashes are escaped by default. Be sure to include two backslashes in any values with file paths in them.

 

Additional connectors

Bitbucket Server is preconfigured with a single connector and, as previously described, the default configuration for that connector can be configured using properties with a server. prefix. For example to change the port from the default 7990 to 7991:

server.port=7991

Bitbucket Server also supports up to five additional connectors and these are configured using properties with prefix server.additional-connector.#, where # is a number between 1 and 5 inclusive. For example, if in addition to the default connector that is configured to listen on port 7990, you wanted to add an SSL secured connector listening on port 8443, you would add these lines to the bitbucket.properties file:

server.additional-connector.1.port=8443
server.additional-connector.1.secure=true
server.additional-connector.1.scheme=https
server.additional-connector.1.proxy-port=443
server.additional-connector.1.ssl.enabled=true
server.additional-connector.1.ssl.client-auth=want
server.additional-connector.1.ssl.protocol=TLSv1.2
server.additional-connector.1.ssl.key-store=/path/to/keystore/bitbucket.jks
server.additional-connector.1.ssl.key-store-password=<password value>

Running Bitbucket behind a reverse proxy secured with SSL

If Bitbucket Server is configured to run behind a reverse proxy that is secured with SSL, the existing server.xml file might contain the following connector configuration:

server.xml
<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" />

 

To achieve the same configuration in Bitbucket Server 5.0 and later, add these entries to the bitbucket.properties file:

bitbucket.properties
server.secure=true
server.scheme=https
server.proxy-port=443
server.proxy-name=mycompany.com

For these examples, if there are less properties in the bitbucket.properties syntax then in the initial server.xml syntax, that indicates the default value would be acceptable and you don't need to add that property to achieve the same result. For example, the port for the default connector is 7990, the default protocol is HTTP/1.1, and so on.

Bitbucket Server secured with SSL-terminating connector

If Bitbucket Server is secured with SSL, where the SSL connection is terminated at the application rather than a proxy, the existing server.xml file might contain the following connector configuration:

server.xml
<Connector port="8443"
    SSLEnabled="true"
    scheme="https"
    secure="true"
    clientAuth="false"
    sslProtocol="TLSv1.2"
    keystoreFile="/path/to/keystore/bitbucket.jks"
    keystorePass="<password value>" />

 

To achieve the same configuration in Bitbucket Server 5.0 and later, add these entries to the bitbucket.properties file:

bitbucket.properties
server.port=8443
server.secure=true
server.scheme=https
server.ssl.enabled=true
server.ssl.client-auth=want
server.ssl.protocol=TLSv1.2
server.ssl.key-store=/path/to/keystore/bitbucket.jks
server.ssl.key-store-password=<password value>
server.ssl.key-password=<password value>

Both ssl.key-store-password and ssl.key-password require explicit configuration. Even if you did not configure both values in the server.xml file, values for both entries need to be explicitly set in bitbucket.properties to secure Bitbucket with SSL.

 

Bitbucket Server secured with SSL and additional connector to redirect HTTP requests

For some with an SSL-terminating connector configured, you might also have an additional connector that redirects HTTP requests to the HTTPS connector. This would have required you to also specify an additional attribute in the <Bitbucket installation directory>/atlassian-bitbucket/WEB-INF/web.xml file. 

Here's what that configuration might have looked like prior to Bitbucket Server 5.0:

server.xml
<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"/>
web.xml
<security-constraint>
  <web-resource-collection>
    <web-resource-name>Restricted URLs</web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint> 

 

To achieve the same configuration in Bitbucket Server 5.0 and later, add these entries to the bitbucket.properties file:

bitbucket.properties
server.require-ssl=true
server.additional-connector.1.port=7990
server.additional-connector.1.redirect-port=8443
server.additional-connector.1.require-ssl=true

 

For these examples, if there are less properties in the bitbucket.properties syntax then in the initial server.xml syntax, that indicates the default value would be acceptable and you don't need to add that property to achieve the same result.

Last modified on Jul 25, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.