Configuring JMX Monitoring to use SSL
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
Summary
Bitbucket Server and Data Center exposes JMX Managed Beans (MBeans) for monitoring application performance and resource consumption. Please see the Enabling JMX counters for performance monitoring documentation for the procedures on how to enable it and to see the list of metrics that can be monitored.
This article is a supplement and describes how to configure JMX monitoring to use Secure Sockets Layer (SSL).
Solution
Two-way authentication with SSL
The diagram below illustrates what's required to configure JMX monitoring with SSL:
The JMX Server and the JMX client have their respective KeyStores and TrustStores, which contain cryptographic artifacts used for public-key cryptography. The KeyStore contains the key pair, which consists of a private key and a certificate with the public key. The TrustStore contains the trusted public certificates. The JMX Client needs to have the JMX Server's public key certificate in its TrustStore, and vice versa.
Set up
Using self-signed certificates
Here are sample procedures for setting up the required components using self-signed certificates:
JMX Client
Repeat the procedures above for the JMX Client. In steps 3 and 4, the destination where the certificate will be imported to would be the JMX Server.
Using certificates from a Certification Authority (CA)
Here are procedures adapted from the Tomcat documentation on installing certificates from a CA. The procedures are the same for both the JMX Server and JMX Client.
Bitbucket JMX Server configuration
JMX settings for Bitbucket can be configured in the <BITBUCKET_INSTALL_DIR>/bin/set-jmx-opts.sh
file.
The script already contains variables that can be set to configure JMX to use SSL.
Here are the variables to update:
Variable | Description |
---|---|
JMX_REMOTE_AUTH | Authentication to use for remote JMX access. Value should be set to "ssl" |
RMI_SERVER_HOSTNAME | IP address / host name of this server that is resolvable by JMX clients |
JMX_REMOTE_PORT | Port for remote JMX support, e.g. 3333 |
JMX_REMOTE_RMI_PORT | random port for RMI data transfer, e.g. 3334 |
JAVA_KEYSTORE | Full path to the Java keystore which must contain Bitbucket's key pair used for SSL authentication for JMX |
JAVA_KEYSTORE_PASSWORD | Password for JAVA_KEYSTORE |
JAVA_TRUSTSTORE | Full path to the Java truststore which must contain the client certificates accepted by Bitbucket for SSL authentication of JMX. |
JAVA_TRUSTSTORE_PASSWORD | Password for JAVA_TRUSTSTORE |
After setting these, restart Bitbucket.
Run JMX Client with SSL
In this sample, jconsole is used as the JMX client.
Run jconsole
and include the following arguments:
Argument | Description |
---|---|
javax.net.ssl.keyStore | JMX Client KeyStore |
javax.net.ssl.keyStorePassword | KeyStore password |
javax.net.ssl.trustStore | JMX Client TrustStore |
javax.net.ssl.trustStorePassword | TrustStore password |
Sample command:
jconsole -J-Djavax.net.ssl.keyStore=/path/to/keystore \
-J-Djavax.net.ssl.keyStorePassword=changeit \
-J-Djavax.net.ssl.trustStore=/path/to/jre/lib/security/cacerts \
-J-Djavax.net.ssl.trustStorePassword=changeit
In the "New Connection" screen in jconsole
, type in the server hostname and port to connect to and click "Connect". Username and password would not be required to connect to the JMX Server. This will initiate a connection to the JMX Server (Bitbucket) using SSL.
Reference: Remote Monitoring with JConsole with SSL Enabled
Only Server is authenticated with SSL
If for any reason, it is not possible to generate the required key pair for the JMX Client, JMX monitoring can be configured to authenticate the JMX Server with SSL while authenticating the JMX Client with the default password authentication method.
Set up
Bitbucket JMX Server configuration
- Create a JMX password file for secure access to JMX monitoring. Follow the JMX password file setup procedures
Create a JMX SSL properties file.
It is just a text (.properties) file with two entries:javax.net.ssl.keyStore=<path/to/keystore> javax.net.ssl.keyStorePassword=<keystore password>
Change the access permissions to this file to restrict access:
chmod 600 <properties file>
Update the
<BITBUCKET_INSTALL_DIR>/bin/set-jmx-opts.sh
file and use the modified script below:Variables to update:
Variable Description RMI_SERVER_HOSTNAME IP address / host name of this server that is reachable / resolvable by JMX clients JMX_REMOTE_PORT Port for remote JMX support, e.g. 3333 JMX_REMOTE_RMI_PORT Random port for RMI data transfer, e.g. 3334 JMX_PASSWORD_FILE Path to JMX password file in Step #1 above JMX_PROPERTIES_FILE Path to JMX SSL properties file in Step #2 above
Run JMX Client
Run jconsole
(no additional arguments required). In the "New Connection" screen in jconsole
, type in the server hostname and port to connect to and click "Connect". Enter the username and password configured in the JMX password file to connect to the JMX Server.
Related Link
Bitbucket Data Center sample deployment and monitoring strategy