Install and configure a remote OpenSearch server
This page describes how to provision a remote OpenSearch server to work with Bitbucket Data Center.
Bitbucket Data Center requires a remote search server, as no search server is bundled or installed for Bitbucket Data Center. OpenSearch is a supported search server distribution for Bitbucket Data Center.
Bitbucket Data Center can have only one remote connection to OpenSearch for your cluster. This may be a standalone OpenSearch installation or a clustered installation behind a load balancer.
For details on how Bitbucket uses the search server, including troubleshooting tips and frequently asked questions, see Administer code search.
On this page
Step 1: Install OpenSearch on a remote machine
We don't provide specific instructions for installing OpenSearch, but a good place to start is the OpenSearch guide for installation.
Step 2: Configure OpenSearch
The opensearch.yml file contains configuration details for your OpenSearch server.
The location of your OpenSearch configuration directory varies depending on how you installed OpenSearch. For installations from an archive the configuration is $OPENSEARCH_HOME/config.
To configure your remote OpenSearch server
Locate the
opensearch.ymlfile within the configuration directory of your OpenSearch server.Add these properties to your opensearch.yml file:
action.auto_create_index: ".watches,.triggered_watches,.watcher-history-*"
network.host: 0.0.0.0Step 3: Secure OpenSearch
Bitbucket communicates to OpenSearch over HTTP using the OpenSearch REST API and can be configured to use basic authentication (a username and password). The OpenSearch provided security plugin can be configured for this purpose.
The minimal distribution of OpenSearch does not contain the OpenSearch security plugin. A custom security solution is required to use the minimal OpenSearch distribution with Bitbucket.
The instructions below describe a simple way to configure the OpenSearch security plugin for the minimum requirements that Bitbucket needs to connect to OpenSearch securely. This is useful if you are migrating from using Elasticsearch with Buckler and want the search server security configuration to work in a similar way, or just want a basic configuration to begin with.
The OpenSearch security plugin also supports many additional features and methods of configuration, which are documented in the OpenSearch security plugin documentation.
Follow the instructions below to secure your remote OpenSearch server with the OpenSearch security plugin. This will involve configuring the OpenSearch security plugin to include a single user in its internal users database called bitbucket with a selected hashed password which has access to the entire search cluster, and a single authentication domain providing basic authentication against the internal users database.
Transport layer TLS
Transport layer TLS is mandatory to use the OpenSearch security plugin (and optionally TLS can also be applied at the REST layer). See the OpenSearch security plugin Configure TLS certificates documentation on how TLS can be configured. Self-signed certificates can be used (provided the plugins.security.ssl.transport.enforce_hostname_verification: false property is set in opensearch.yml) and can be generated using a tool like OpenSSL. Place the generated certificates or keystore/truststore files in the $OPENSEARCH_HOME/config directory.
Security configuration
Replace the configuration files in $OPENSEARCH_HOME/plugins/opensearch-security/securityconfig/ with the following:
_meta:
type: "actiongroups"
config_version: 2_meta:
type: "audit"
config_version: 2
config:
# enable/disable audit logging
enabled: false_meta:
type: "config"
config_version: 2
config:
dynamic:
authc:
basic_internal_auth_domain:
description: "Authenticate via HTTP Basic against internal users database"
http_enabled: true
transport_enabled: true
order: 1
http_authenticator:
type: basic
challenge: true
authentication_backend:
type: intern_meta:
type: "internalusers"
config_version: 2
bitbucket:
hash: "##REPLACE WITH HASHED PASSWORD##"
backend_roles:
- "admin"
description: "Admin user"_meta:
type: "nodesdn"
config_version: 2_meta:
type: "roles"
config_version: 2_meta:
type: "rolesmapping"
config_version: 2
all_access:
reserved: false
backend_roles:
- "admin"
description: "Maps admin to all_access"_meta:
type: "tenants"
config_version: 2_meta:
type: "whitelist"
config_version: 2
config:
enabled: falseThe important files are config.yml, internal_users.yml, and roles_mapping.yml:
a. config.yml: defines a single authenticator, which is using basic authentication on both HTTP and transport, backed by the internal user database
b. internal_users.yml: creates a single user with username bitbucket (and a provided hashed password, see Generate a password step below), and this user is assigned the admin back-end role
c. roles_mapping.yml: assigns the admin backend role (that the bitbucket user has) the all_access role, which is a pre-defined role by the OpenSearch security plugin that gives access to the entire search server
d. The remaining files are empty placeholders that the OpenSearch security plugin requires.
Generate a password
Generate a hashed password for the bitbucket user using the OpenSearch provided hashing tool $OPENSEARCH_HOME/plugins/opensearch-security/tools/hash.sh. Copy the hashed password into internal_users.yml, replacing the password placeholder.
This password is what Bitbucket will use to connect to OpenSearch.
OpenSearch configuration
To configure OpenSearch security the following properties also need to be added to opensearch.yml:
#This property causes the OpenSearch security plugin to configure itself based on
#the security configuration yml files if no security configuration exists in on the
#search server yet (e.g. on first start).
plugins.security.allow_default_init_securityindex: true
#The REST API is locked down by default, even to the 'all_access' roll, so enable
#the 'all_access' role to be able to use it here.
plugins.security.restapi.roles_enabled: ["all_access"]
#Transport layer TLS is mandatory. The certificates need to be manually added to the
#OpenSearch config folder. The example settings below are for X.509 certificates and
#PKCD #8 keys, but a keystore and truststore approach can also be used. Refer to the
#OpenSearch security plugin documentation for more information.
plugins.security.ssl.transport.pemcert_filepath: node.pem
plugins.security.ssl.transport.pemkey_filepath: node-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
#If the generated certificates are self-signed then hostname verification must be
#disabled.
#plugins.security.ssl.transport.enforce_hostname_verification: falseStart your remote OpenSearch server.
When using plugins.security.allow_default_init_securityindex: true, changing the configuration files in $OPENSEARCH_HOME/plugins/opensearch-security/securityconfig/ after the first startup of OpenSearch will not have any effect, as the files are only used automatically for the default initialisation of the security index.
To modify configuration later, you can either use the securityadmin.sh script or the REST API.
Step 4: Connect OpenSearch to Bitbucket
Once you've configured your OpenSearch server, you then need to connect it to Bitbucket.
To configure your remote OpenSearch server using the bitbucket.properties file
bitbucket.properties file, it cannot be edited later from the admin UI. Any changes that need to be made to the OpenSearch configuration, must be made within the bitbucket.properties file and require a restart of Bitbucket to be applied.
- Locate the
bitbucket.propertiesfile in the<Bitbucket home directory>/shareddirectory. Add the details of your OpenSearch server:
<Bitbucket home directory>/shared/bitbucket.propertiesplugin.search.config.baseurl=<search server URL> #e.g. http://localhost:9200/ plugin.search.config.username=<username> #e.g. bitbucket plugin.search.config.password=<password> #e.g. the password that was hashedStart Bitbucket without starting the bundled search server.
Bitbucket Data Center Bitbucket Data Center does not install the bundled search server, so will always start without it.
Bitbucket Server on Linux (not a service) start-bitbucket.sh --no-searchBitbucket Server on Linux (as a service) Modify your start service script to pass --no-search to start-bitbucket.sh.
Bitbucket Server on Windows (not a service) start-bitbucket.bat /no-searchBitbucket Server on Windows (as a service) Do not start the bundled search service
Your remote OpenSearch server is now configured to work with Bitbucket.