Enabling JMX Support for the JRE of the Target Application

Prior to adding a new Jmx test, you need to enable the JMX support for the JRE of the target application. The steps for the same differ according to the authentication/security status of JMX. By default, JMX requires no authentication or security (SSL). In this case therefore, to use JMX for pulling out metrics from a target application, the following will have to be done:

  1. Login to the application host.

  2. The <JAVA_HOME>\jre\lib\management folder used by the target application will typically contain the following files:

    • management.properties
    • jmxremote.access
    • jmxremote.password.template
    • snmp.acl

  3. Edit the managerment.properties file, and append the following lines to it:

    com.sun.management.jmxremote.port=<Port No>

    com.sun.management.jmxremote.ssl=false com.sun.management.jmxremote.authenticate=false

    For instance, if the JMX listens on port 9005, then the first line of the above specification would be:

    com.sun.management.jmxremote.port=9005

  4. Then, save the file.

  5. Next, edit the start-up script of the target application, and add the following line to it:

    Dcom.sun.management.config.file=<management.properties_file_path>

  6. For instance, on a Windows host, the <management.properties_file_path> can be expressed as: D:\bea\jrockit_150_11\jre\lib\management.
  7. On other hand, on a Unix/Linux/Solaris host, a sample <management.properties_file_path> specification will be as follows: /usr/jdk1.5.0_05/jre/lib/management.
  8. Save this script file too.

  9. Next, during test configuration, do the following:

    • Set jmx as the mode;
    • Set the port that you defined in step 3 above (in the management.properties file) as the jmx remote port;
    • Set the user and password parameters to none.
    • Update the test configuration.

On the other hand, if JMX requires only authentication (and no security), then the following steps will apply:

  1. Login to the application host. If the application is executing on a Windows host, then, login to the host as a local/domain administrator.

  2. As stated earlier, the <JAVA_HOME>\jre\lib\management folder used by the target application will typically contain the following files:

    • management.properties
    • jmxremote.access
    • jmxremote.password.template
    • snmp.acl.template
  3. First, copy the jmxremote.password.template file to any other location on the host, rename it as as jmxremote.password, and then, copy it back to the <JAVA_HOME>\jre\lib\management folder.
  4. Next, edit the jmxremote.password file and the jmxremote.access file to create a user with read-write access to the JMX. To know how to create such a user, refer to Securing the ‘jmxremote.password’ file.
  5. Then, proceed to make the jmxremote.password file secure by granting a single user “full access” to that file. For monitoring applications executing on Windows in particular, only the Owner of the jmxremote.password file should have full control of that file. To know how to grant this privilege to the Owner of the file, refer to Configuring the eG Agent to Support JMX Authentication.

  6. In case of applications executing on Solaris / Linux hosts on the other hand, any user can be granted full access to the jmxremote.password file, by following the steps below:

    • Login to the host as the user who is to be granted full control of the jmxremote.password file.

    • Issue the following command:

      chmod 600 jmxremote.password

    • This will automatically grant the login user full access to the jmxremote.password  file.

  7. Next, edit the management.properties file, and append the following lines to it:

    com.sun.management.jmxremote.port=<Port No>

    com.sun.management.jmxremote.ssl=false com.sun.management.jmxremote.authenticate=true com.sun.management.jmxremote.access.file=<Path of jmxremote.access> com.sun.management.jmxremote.password.file=<Path of jmxremote.password>

    For instance, assume that the JMX remote port is 9005, and the jmxremote.access and jmxremote.password files exist in the following directory on a Windows host:  D:\bea\jrockit_150_11\jre\lib\management. The specification above will then read as follows:

    com.sun.management.jmxremote.port=9005

    com.sun.management.jmxremote.access.file=D:\\bea\\jrockit_150_11\\jre\\lib\\management\\jmxremote.access

    com.sun.management.jmxremote.password.file=D:\\bea\\jrockit_150_11\\jre\\lib\\management\\jmxremote.password

  8. If the application in question is executing on a Unix/Solaris/Linux host, and the jmxremote.access and jmxremote.password files reside in the /usr/jdk1.5.0_05/jre/lib/management folder of the host, then the last 2 lines of the specification will be:

    com.sun.management.jmxremote.access.file=/usr/jdk1.5.0_05/jre/lib/management/jmxremote.access
    com.sun.management.jmxremote.password.file=/usr/jdk1.5.0_05/jre/lib/management/jmxremote.password

  9. Finally, save the file.

  10. Then, edit the start-up script of the target application, include the following line in it, and save the file:

    Dcom.sun.management.config.file=<management.properties_file_path>

  11. For instance, on a Windows host, the <management.properties_file_path> can be expressed as: D:\bea\jrockit_150_11\jre\lib\management.

  12. On other hand, on a Unix/Linux/Solaris host, a sample <management.properties_file_path> specification will be as follows: /usr/jdk1.5.0_05/jre/lib/management.

    Note:

    eG Enterprise cannot use JMX that requires both authentication and security (SSL), for monitoring the target Java application.

Securing the ‘jmxremote.password’ file

To enable the eG agent to use JMX (that requires authentication only) for monitoring a Windows-based Java application, you need to ensure that the jmxremote.password file in the <JAVA_HOME>\jre\lib\management folder used by the target application is accessible only by the Owner of that file. To achieve this, do the following:

  1. Login to the Windows host as a local/domain administrator.
  2. Browse to the location of the jmxremote.password file using Windows Explorer.

  3. Next, right-click on the jmxremote.password file and select the Properties option (see Figure 1).

    Figure 1 : Selecting the Properties option

  4. From Figure 2 that appears next, select the Security tab.

    Figure 2 : The Properties dialog box

    However, if you are on Windows XP and the computer is not part of a domain, then the Security tab may be missing. To reveal the Security tab, do the following:

    • Open Windows Explorer, and choose Folder Options from the Tools menu.

    • Select the View tab, scroll to the bottom of the Advanced Settings section, and clear the check box next to Use Simple File Sharing.

      Figure 3 : Deselecting the ‘Use simple file sharing’ option

    • Click OK to apply the change
    • When you restart Windows Explorer, the Security tab would be visible.

    • Next, select the Advanced button in the Security tab of Figure 4.

      Figure 4 : Clicking the Advanced button

  5. Select the Owner tab to see who the owner of the file is.

    Figure 5 : Verfying whether the Owner of the file is the same as the application Owner

  6. Then, proceed to select the Permissions tab from Figure 6 to set the permissions. If the jmxremote.password file has inherited its permissions from a parent directory that allows users or groups other than the Owner to access the file, then clear the Inherit from parent the permission entries that apply to child objects check box in Figure 6.

    Figure 6 : Disinheriting permissions borrowed from a parent directory

  7. At this point, you will be prompted to confirm whether the inherited permissions should be copied from the parent or removed. Press the Copy button in Figure 7.

    Figure 7 : Copying the inherited permissions

  8. Next, remove all permission entries that allow the jmxremote.password file to be accessed by users or groups other than the file Owner. For this, click the user or group and press the Remove button in Figure 7. At the end of this exercise, only a single permission entry granting Full Control to the owner should remain in Figure 8.

    Figure 8 : Granting full control to the file owner

  9. Finally, click the Apply and ok buttons to register the changes. The password file is now secure, and can only be accessed by the file owner.

Configuring the eG Agent to Support JMX Authentication

If the eG agent needs to use JMX for monitoring a Java application, and this JMX requires authentication only (and not security), then any new jmx test created using the Integration Console component should be configured with the credentials of a valid user to JMX, with read-write rights. The steps for creating such a user are detailed below:

  1. Login to the application host. If the application being monitored is on a Windows host, then login as a local/domain administrator to the host.

  2. Go to the <JAVA_HOME>\jre\lib\management folder used by the target application to view the following files:

    • management.properties
    • jmxremote.access
    • jmxremote.password.template
    • snmp.acl.template
  3. Copy the jmxremote.password.template file to a different location, rename it as jmxremote.password, and copy it back to the <JAVA_HOME>\jre\lib\management folder.

  4. Open the jmxremote.password file and scroll down to the end of the file. By default, you will find the commented entries indicated by Figure 9 below:

    Figure 9 : Scrolling down the jmxremote.password file to view 2 commented entries

  5. The two entries indicated by Figure 9 are sample username password pairs with access to JMX. For instance, in the first sample entry of Figure 9, monitorRole is the username and QED is the password corresponding to monitorRole. Likewise, in the second line, the controlRole user takes the password R&D.

  6. If you want to use one of these pre-defined username password pairs during test configuration, then simply uncomment the corresponding entry by removing the # symbol preceding that entry. However, prior to that, you need to determine what privileges have been granted to both these users. For that, open the jmxremote.access file in the editor.

    Figure 10 : The jmxremote.access file

  7. Scrolling down the file (as indicated by Figure 10) will reveal 2 lines, each corresponding to the sample username available in the jmxremote.password file. Each line denotes the access rights of the corresponding user. As is evident from Figure 10, the user monitorRole has only read-only rights, while user controlRole has readwrite rights. Since the eG agent requires readwrite rights to be able to pull out key JVM-related statistics using JMX, we will have to configure the test with the credentials of the user controlRole.

  8. For that, first, edit the jmxremote.password file and uncomment the controlRole <password> line as depicted by Figure 11.

    Figure 11 : Uncommending the ‘controlRole’ line

  9. Then, save the file. You can now proceed to configure the tests with the user name controlRole and password R&D.
  10. Alternatively, instead of going with these default credentials, you can create a new username password pair in the jmxremote.password file, assign readwrite rights to this user in the jmxremote.access file, and then configure the eG tests with the credentials of this new user. For instance, let us create a user john with password john and assign readwrite rights to john.

  11. For this purpose, first, edit the jmxremote.password file, and append the following line (see Figure 12) to it:

    john   john

    Figure 12 : Appending a new username password pair

  12. Save the jmxremote.password file.

  13. Then, edit the jmxremote.access file, and append the following line (see Figure 13) to it:

    john   readwrite

    Figure 13 : Assigning rights to the new user in the jmxremote.access file

  14. Then, save the jmxremote.access file.
  15. Finally, proceed to configure the tests with the user name and password, john and john, respectively.