Skip to main content

Configuring Nexus Repository 3 To Allow JMX Connections

.

What is JMX

JMX is short for Java Management Extensions. It is a Oracle Java technology that can be used to manage applications running inside the Java Virtual Machine (JVM) through standard interfaces and models.

Why Use JMX

The most common use case to connect to Sonatype products using JMX is to monitor the internals of the application at a low level. Research can be conducted on thread activity, memory consumption, CPU cycles, I/O use, and other application-specific performance data.

A more advanced use case would be to adjust the low-level settings of the application. While modifying application configuration using JMX is powerful, it can bypass many of the safeguards one would normally encounter in a REST API, JAVA API, or web browser user interface. Modifying the JVM internals your Sonatype product is running in should only be done on the advice of Sonatype support.

High-Level Architecture

Inside the JVM, data models are registered as Managed Beans (MBeans) and then exposed using an MBean Server. The server accepts connections using an RMI Connector. The RMI connector does NOT use HTTP or what is commonly known as REST - you need to use a special client that understands the JMX protocols.

A JMX Connector client, such as VisualVM, can connect to the listening server. Once connected. the client can view or manage the registered Mbeans provided the host network allows remote connections and the client can authenticate.

JMX Connector Clients

Popular JMX Connector clients are:

  1. jconsole - included with the Oracle JDK
  2. VisualVM - can be downloaded standalone or is included with the Oracle JDK
  3. Oracle Java Mission Control - bundled with the HotSpot JVM 

Local and Remote JMX Connections

There are two ways to connect using JMX - locally and remotely.

Local connections are connections made by a client on the same host as the MBean server. These are possible without any extra configuration as long as the following conditions are met:

  • the JMX client and Sonatype product process are owned by the same user id
  • the JMX client and Sonatype product use the exact same Java version and architecture: Example 64 bit Java 7 for both.

Remote connections from other hosts require:

  • explicit Nexus Repository 3 product configuration changes to enable the remote access feature
  • a username and password with the valid credentials and authorization to MBeans
  • firewall and networking which allow tcp connections to be established between hosts

Enabling JMX Remote Access

The JMX Remote Access feature is not enabled by default.

These steps outline how to enable the JMX Remote Access feature:

1. Edit etc/karaf/org.apache.karaf.features.cfg and add management to the list of comma-separated features in the featuresBoot property

2. Edit etc/karaf/org.apache.karaf.management.cfg file.
Adjust the ports listed to free ports which you want to use for RMI connections.
Edit both the rmiRegistryHost and rmiServerHost properties to be the IPv4 address that the remote JMX client can use to reach your Nexus Repository 3 host system. Take note of the format of the serviceUrl property.

3. Stop Nexus Repository 3 

4. Start Nexus Repository 3 

At this point, the JMX Remote Access feature should be enabled. To allow access from specific clients you need to authenticate with a user that has the correct privileges.

JMX Remote Access Authentication and Authorization

Unlike JMX Local Access, all JMX Remote Access requires an authenticated and authorized connection.

Understanding JMX Remote Access Privilege Model

The Nexus Repository 3 ships with a basic privilege model for MBeans access:

  • view only access to any Mbean method names matching list*,get*,is*
  • write access to any MBean method names matching set* or any other non-matched managed method name ( * )

While a more in-depth model can be defined inside of etc/karaf/jmx.acl.cfg , customizing this model is outside the scope of this document.

JMX Remote Access for Nexus Repository Administrators

All user accounts assigned the nx-admin role are granted full access to all exposed MBeans - for example, the default admin user has this role.

JMX Remote View-Only Access Using Custom Roles

Once you have enabled the JMX Remote Access feature, you may wish to define a custom role that allows some users view-only access to MBean methods

  1. Sign in as an Administrator to the repository manager configuration user interface.
  2. Using Roles -> Create Nexus Role, create a role named karaf-viewer. You do not need to assign other roles or privileges to this role in order to Save the new role.
  3. Assign karaf-viewer role to a non-administrator user that can authenticate to the repository manager
  4. Authenticate using a JMX client as the JMX user assigned the custom role. This user should only be able to view any Mbean method names matching list*,get*,is*

JMX Remote Write Access Using Custom Roles

Once you have enabled the JMX Remote Access feature, you may wish to define a user with full access to Mbeans, without making that user a regular Nexus Repository Administrator.

  1. Sign in as an Administrator to the repository configuration user interface.
  2. Using Roles -> Create Nexus Role, create a role named karaf-viewer. You do not need to assign other roles or privileges to this role in order to Save the new role.
  3. Using Roles -> Create Nexus Role, create a role named karaf-admin. You do not need to assign other roles or privileges to this role in order to Save the new role.
  4. Assign karaf-viewer and karaf-admin role to a non-administator user that can authenticate to the Nexus Repository.
  5. Authenticate using a JMX client as the JMX user assigned the custom roles. This user should have full access to any MBeans

JMX Remote Access Using a Client

Using a JMX client from another host, try to connect to Nexus Repository using an RMI Connector URI of this form, substituting the matching values from your org.apache.karaf.management.cfg file.

service:jmx:rmi://${rmiServerHost}:${rmiServerPort}/jndi/rmi://${rmiRegistryHost}:${rmiRegistryPort}/karaf-${karaf.name}

For example:

service:jmx:rmi://192.168.2.97:8044/jndi/rmi://192.168.2.97:8099/karaf-root

Make sure that you also specify a user and password that has one of the required roles, or you will get an authorization error when listing MBeans resources.

On Linux, make sure the command: hostname -i returns the same ip address used by your JMX client to connect to this host (and not just "127.0.0.1"). Such a /etc/hosts configuration can result in connection timeouts from JMX clients. You can solve this by either editing /etc/hosts to return the public ip, or by adding the following system property to nexus.vmoptions and restarting Nexus Repository:

-Djava.rmi.server.hostname=192.168.2.97

Eclipse Jetty Related MBeans

As of Nexus Repository 3.39.0, additional Eclipse Jetty related MBeans are exposed by default.