Registration

Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
http://scn.sap.com
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

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?

  
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

    CommandDetails
    icacls jmxremote.password /setowner BOE-SVCWhere BOE-SVC is the user account that your Apache Tomcat service is running under
    icacls jmxremote.password /grant BOE-SVC:FWhere BOE-SVC is the user account that your Apache Tomcat service is running under
    icacls jmxremote.password /inheritance:rThis 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.

    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:

     

     

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

       
  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

        

  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
  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


  • No labels

14 Comments

  1. Looks like the download links to the JMX listener JAR is out dated.

    Here's a link to the Apache downloads where you should be able to find the JAR

    http://tomcat.apache.org/download-80.cgi

     

    1. Thanks Brian, I updated the links.

      1. Former Member

        Hi Toby,

        When running the following command to setup required file permission;

        icacls jmxremote.password /setowner BOE-SVC  Where BOE-SVC is the user account that your Apache Tomcat service is running under

        What account should i provide if my Tomcat is running under Local System account? Thanks in advance!

        -Praveen

        1. Hi Praveen,

          The user for LocalSystem would be just: System

          Keep in mind that you can't logon as System account so changing the file after you've set this would require server admin account.  So, depending on your situation it may be best to run Tomcat as another user account and set file permissions on this.

          Regards
          Toby

  2. Former Member

    Hi Toby,

    I have configured JMX with FW support and everything went well. I was able to see Tomcat listening on both 10001 and 10002 and I also tested in communications analyzer in BIP support tool and was able to make a successful connection on 10001 and 10002 ports to Tomcat server but i still get the error message when i try to validate the JMX settings. I'm guessing there is some issue for Tomcat server communicating back to server where BIP support tool client is installed. Any suggestions on what might be the issue? I tried to attach the error message but i cant. Here is the error what i see when i validate: JMX Validation Error JMX configuration validation failed for this node Thanks in advance!

    -Praveen

     

    1. Praveen, do you run the services under a service account, or local system?

      If local system, then this probably isn't your issue. I run all services under a service account. If you do, this may be your issue as it hits me every time I patch or do a system upgrade, and I always forget about it. The Tomcat service gets switched to run under local system instead of my service account. As soon as I stop Tomcat and change it to logon as my designated service account, I can then validate the JMX configuration. You may want to check this.

    2. Hi Praveen,

      It could be an issue with network address translation.  When you configured JMX Remote Listener in server.xml did you add the property rmiBindAddress?  Is the value for this property the host name of the Tomcat server?  

      After the initial JMX handshakre on port 10001, Tomcat will respond to the BIPST client with the second port (10002) and the hostname as specified in rmiBindAddress property and then communication will continue on this hostname:port.

      Is this hostname resolvable from the BIPST client?  Are you using this name (as specified by rmiBindAddress) when you tested the connection in Connection Analyzer?  

      Thanks
      Toby

      1. Former Member

        Hi Toby,

        I was able to validate the JMX settings now. It was not the port issue though. Different passwords in password file and JMX settings. Thank you for help again!

        -Praveen

        1. Great.  Do you still have issues validating the SAP Host Agent?

          1. Former Member

            No, everything is working fine for me. Thanks for checking!

            1. Ok thanks for the update!

  3. Former Member

    Hi Toby,

    We are configuring the BI support tool to trust the CA and was wondering how do i change the default trusted certificate authority password?

    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

     

    1. Hi Praveen,

      You can use keytool to do this:

      <BISTHOME>\BISupport\bin\keytool -storepasswd -new theNewPassword -keystore "<BISTHOME>\BISupport\lib\security\cacerts"

      Cheers
      Toby

      1. Former Member

        Thanks Toby!