How to configure JMX for Apache Tomcat (Windows)

This document provides tutorials on how to enable the JMX listener on Apache Tomcat running on Windows.  The JMX protocol allows remote monitoring and managing of Apache Tomcat.  For more information, refer to Apache Tomcat Monitoring and Managing Tomcat.

   
Which type of configuration should be used?

• If the Apache Tomcat instance is used for sandbox or test purposes, you can use the no authentication option
• If the Apache Tomcat instance is used for sandbox or test purposes and there is Network Address Translation between the BIPST client and Apache Tomcat server, refer to the (no authentication) with network address translation (NAT) option
• If the Apache Tomcat instance is used for production purposes, you should configure JMX user authentication with ReadOnly access.  Refer to the (with authentication) option
• If there is a firewall between the BIPST client and Apache Tomcat, you should configure the with Firewall Support option

  
Configuring JMX for Apache Tomcat (no authentication)

1. On your Tomcat host, open the start menu and click on Tomcat Configuration (alternatively, edit the catalina.bat or catalina.sh)
       

2. Click on the Java tab, then add the following Java Options
      

   -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8008 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false

        

3. Save the changes and restart Tomcat

Configuring Apache Tomcat (no authentication) for Network Address Translation (NAT)

   
If there is a Network Address Translation between your BIPST client and the Apache Tomcat, you need to add one additional property to support this.  

1. On your Tomcat host, open the start menu and click on Tomcat Configuration (alternatively, edit the catalina.bat or catalina.sh)
       

2. Click on the Java tab, then add an additional Java Option (in red below)
   

   -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8008 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=TomcatHostName

   ** Where TomcatHostName is the hostname of your Tomcat server
    

3. Save the changes and restart Tomcat
      

4. On your BIPST client, edit your hosts file in the location:  C:\Windows\System32\drivers\etc.  Add an entry for your Tomcat host with the resolvable IP Address of the Tomcat host.  For example:
   
   

   10.165.10.120   TomcatHostName   TomcatHostName.domain.com

   
       

Configuring JMX for Apache Tomcat (with Authentication)

1. On your Tomcat host browse to %CATALINA_BASE%\conf
       
2. In the conf directory, create a new blank text file and save it with the name jmxremote.access
       
3. In the conf directory, create another blank text file and save it with the name jmxremote.password
      
   
    

4. Edit the file jmxremote.access with a text editor and add the below text and save the changes (where jmxuser is the name of the user that will connect to the JMX listener)
   
   

5. Edit the file jmxremote.password with a text editor and define a password for your jmxuser (replace ThePassword123 with a password of your choosing)
     
   
     

6. Next, open a command prompt and browse to the folder where jmxremote.password is located
     
   
        

7. Run the following commands in order to setup the required file permission

   Command	Details
   icacls jmxremote.password /setowner BOE-SVC	Where BOE-SVC is the user account that your Apache Tomcat service is running under
   icacls jmxremote.password /grant BOE-SVC:F	Where BOE-SVC is the user account that your Apache Tomcat service is running under
   icacls jmxremote.password /inheritance:r	This command removes inherited permissions from users except the owner

   
   

8.      Go to START, Programs, Tomcat Configuration.  Click on the Java tab and add the following Java Options
   
   

   -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8008 -Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.password.file=C:/Program Files (x86)/SAP BusinessObjects/tomcat/conf/jmxremote.password -Dcom.sun.management.jmxremote.access.file=C:/Program Files (x86)/SAP BusinessObjects/tomcat/conf/jmxremote.access

   

   In this example, the path C:/Program Files (x86)/SAP BusinessObjects/tomcat/conf is the location where the jmxremote files are stored. This path may change depending on your install location.

   
   
   

9. Restart Apache Tomcat for the changes to take affect.

   If the Apache Tomcat service fails to start, make sure you have correctly configured file permissions and have not made any mistakes in the Java Options (step 8).

   Check the Apache Tomcat stderr.log for additional troubleshooting information

    

    

    

    

Configuring JMX for Apache Tomcat with Firewall Support

These instructions are applicable if there is a firewall blocking TCP ports between the BIPST client and the Apache Tomcat server.  For more information regarding this setup, refer to JMX Remote Lifecycle Listener,
    

1. Download the file catalina-jmx-remote.jar from Apache.org according to your version of Apache Tomcat (only applies if using Tomcat 7 or Tomcat 8).  NOTE: Tomcat 9 has this functionality built in by default.

   Check your exact build version of Tomcat and use the matching catalina-jmx-remote-jar

   It's important to get the correct version of catalina-jmx-remote.jar that matches your exact Tomcat build version. To check the Tomcat version, browse to the Tomcat homepage: for example http://servername:8080

   

   Find the correct catalina-jmx-remote.jar file by browsing to /version/bin/extras/ in the below links:

   Tomcat 7 Current Versions: https://tomcat.apache.org/download-70.cgi
   Tomcat 7 Archives: https://archive.apache.org/dist/tomcat/tomcat-7/

   Tomcat 8 Current Versions: https://tomcat.apache.org/download-80.cgi
   Tomcat 8 Archives: https://archive.apache.org/dist/tomcat/tomcat-8/
   
   

   For example:

   Tomcat Version	Download Link
   Apache Tomcat 7.0.92	http://mirror.csclub.uwaterloo.ca/apache/tomcat/tomcat-7/v7.0.92/bin/extras/catalina-jmx-remote.jar
   Apache Tomcat 8.0.50	http://apache.mirror.iweb.ca/tomcat/tomcat-8/v8.0.50/bin/extras/catalina-jmx-remote.jar

   If using Tomcat 9: This step is not required

    

    

2. On your Tomcat host, copy the file catalina-jmx-remote.jar to %CATALINA_BASE%\lib  
   
   

   If using Tomcat 9: This step is not required)

   
     
   
      

3. Browse to %CATALINA_BASE%\conf and edit the file server.xml with a text editor
    

4. Enable the new JMX Remote listener by adding the following tag to server.xml (where TomcatHostName is the host name of the server where Apache Tomcat is running)
   
   

   <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener" rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" rmiBindAddress="TomcatHostName" />

     
   
   
   

5. Save the changes to server.xml
      

6. Click on START, Programs, Tomcat Configuration then click on the Java tab and add the following Java Options
     
   No Authentication Option

   -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false

      
   With Authentication Option (NOTE: you must first have configured the jmxremote authentication files per this tutorial)
   

   -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.password.file=C:/Program Files (x86)/SAP BusinessObjects/tomcat/conf/jmxremote.password -Dcom.sun.management.jmxremote.access.file=C:/Program Files (x86)/SAP BusinessObjects/tomcat/conf/jmxremote.access

   Tomcat 9 requires additional property

   -Dcom.sun.management.jmxremote.registry.ssl=false

       
   
   

7. Save the changes and restart the Apache Tomcat service.  Note that Apache Tomcat is now listening on two ports (in this example 10001 and 10002)
      
   
       

   If the Apache Tomcat service fails to start, make sure that you have not made a mistake in the server.xml and that the ports 10001 and 10002 are not in use by other processes.

   Check the Apache Tomcat stderr.log for additional troubleshooting information.

   Ensure you have downloaded the correct jmx-remote.jar file for your version of Tomcat, otherwise the Apache Tomcat service may fail to start. The following error can occur in the stderr.log when using an incompatible version of the jmx-remote.jar

   Java.lang.unsupportedclassversionerror: .org/Apache/Catalina/Mbeans/JMXRemoteLifecycleListener: unsupported major.minor version 51.0.

8. Open TCP ports 10001 and 10002 on the firewall for communication between the BIPST client and the Apache Tomcat server

Configuring JMX SSL for Apache Tomcat

Parameters in bold should be replaced with values appropriate to your environment

Configure Tomcat to use SSL

1. Navigate to the following folder, or any Java folder if using an external Tomcat Web Application Server in a command line window on the server where Tomcat is running
   1. C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\win64_x64\sapjvm\bin
2. Generate a Java Keystore for Tomcat
   1. Run: keytool -genkeypair -alias myserver -keyalg RSA -keystore "C:/TomcatSSL/keystore.jks" -keysize 2048 -storepass Password1
3. Create a certificate signing request for the keystore
   1. Run: keytool -certreq -alias myserver -keystore "C:/TomcatSSL/keystore.jks" -file "C:/TomcatSSL/myserver.csr" -storepass Password1
4. Provide the myserver.csr file to your certificate authority to sign
   1. To self-sign the certificate, follow the instructions here
   2. The certificate authority should provide two files, a certificate authority file such as cacert.pem and your signed certificate, myserver.pem OR a single file containing all certificates
5. Import the signed certificate into the existing keystore
   1. Run: keytool -import -trustcacerts -alias myserver -file "C:/TomcatSSL/myserver.pem" -keystore "C:/TomcatSSL/keystore.jks"
6. Validate that the certificate is correctly stored in the keystore
   1. keytool -list -v -keystore "C:/TomcatSSL/keystore.jks" -storepass Password1
   2. 
7. Modify Tomcat Java properties and change, or add the following:

   1. -Dcom.sun.management.jmxremote.ssl=true -Dcom.sun.management.jmxremote.ssl.need.client.auth=false -Djavax.net.ssl.keyStore=C:\TomcatSSL\keystore.jks -Djavax.net.ssl.keyStorePassword=Password1

8. Restart Tomcat

Configure BI Platform Support Tool to Trust the CA

1. Copy cacert.pem to the computer running BI Platform Support Tool
2. Import the self-signed certificate, or CA certificate to the trusted certificate file
3. Open a command line window and navigate to the <BISTHOME>\BISupport\bin folder
4. Run: keytool -import -trustcacerts -file cacert.pem -alias CA_Alias -keystore "<BISTHOME>\BISupport\lib\security\cacerts" -storepass changeit
   1. Note: The default password for the trusted certificate authority file is changeit
5. Start BI Platform Support Tool
6. Navigate to Landscape Configuration
7. Check "Enable Java SSL"
8. Set the Java Truststore to <BIPSTHOME>\BISupport\lib\security\cacerts
9. Set the Java Truststore password to the password for the cacerts file
   1. Note: The default password for the trusted certificate authority file is changeit
10. Click Save Changes

11. Restart BI Platform Support Tool   

12. From Landscape Configuration select the Tomcat Server
13. Navigate to the JMX Settings tab and click Validate

Note: All Tomcat Java Application Servers should be signed using the same Certificate Authority, therefore it is only necessary to configure the BI Platform Support Tool once.

Optional: Configure Client Certificate Authentication for JMX

Part 1: Generate a client certificate

1. Open a command window and navigate to the <BISTHOME\BISupport\bin directory on the client machine running BI Platform Support Tool
2. Generate a Java Keystore for BI Platform Support Tool
   1. Run: keytool -genkeypair -alias BIPST -keyalg RSA -keystore "C:/BIPST/keystore.jks" -keysize 2048 -storepass Password1
3. Create a certificate signing request for the keystore
   1. Run: keytool -certreq -alias BIPST -keystore "C:/BIPST/keystore.jks" -file "C:/BIPST/BIPST.csr" -storepass Password1
4. Provide the BIPST.csr file to your certificate authority to sign
   1. To self-sign the certificate, follow the instructions here
   2. The certificate authority should provide two files, a certificate authority file such as cacert.pem and your signed certificate, BIPST.pem OR a single file containing all certificates
5. Import the signed certificate into the existing keystore
   1. Run: keytool -import -trustcacerts -alias BIPST -file "C:/BIPST/BIPST.pem" -keystore "C:/BIPST/keystore.jks"
6. Validate that the certificate is correctly stored in the keystore
   1. keytool -list -v -keystore "C:/BIPST/keystore.jks" -storepass Password1

Part 2: Configure Tomcat to trust the BIPST certificate

1. Copy cacert.pem, or the single certificate file to the computer running Tomcat
2. Navigate to the Tomcat Java directory - The default directory is below
   1. C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\win64_x64\sapjvm\bin
3. Import the certificate into the Tomcat cacerts keystore
   1. keytool -import -trustcacerts -alias cacert -file "C:/BIPST/cacert.pem" -keystore "C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\win64_x64\sapjvm\jre\lib\security\cacerts"
4. Open Tomcat configuration
5. Modify or add the following lines to the Java arguments

   1. -Dcom.sun.management.jmxremote.ssl.need.client.auth=true

6. Restart Tomcat

Part 3: Configure BIPST to use the client certificate

1. Launch BI Platform Support Tool
2. Navigate to Landscape Configuration and select your landscape
3. Set the Keystore and Keystore Password fields to "C:/BIPST/keystore.jks" and "Password1"
4. Save and restart BI Platform Support Tool

Troubleshooting failed JMX Connections

Refer to:  Troubleshooting failed JMX connections with JConsole