Enabling RMI

By default, the RMI port in the Meridian server is disabled, for security reasons. To enable it so that you can access Meridian through jconsole or remote-manage Meridian, you will have to add some settings to the default Meridian install.

To enable the RMI port in Meridian, add the following to the ${OPENNMS_HOME}/etc/opennms.conf file. If you do not have an opennms.conf file, you can create it.

# Configure remote JMX
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.port=18980"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.local.only=false"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.authenticate=true"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.ssl=false"

# Listen on all interfaces
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dopennms.poller.server.serverHost=0.0.0.0"
# Accept remote RMI connections on this interface
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Djava.rmi.server.hostname=<your-server-ip-address>"

This tells Meridian to listen for RMI on port 18980, and to listen on all interfaces. (Originally, RMI was used only for the legacy Remote Poller, so despite the property name mentioning the "opennms poller server" it applies to RMI as a whole.) Note that you must include the -Djava.rmi.server.hostname= option or Meridian will accept connections on the RMI port, but not be able to complete a valid connection.

Authentication will be allowed only for users that are in the admin role (i.e., ROLE_ADMIN), or the jmx role (i.e., ROLE_JMX). To make a user an admin, be sure to add only the ROLE_ADMIN role to the user in users.xml. To add the jmx role to the user, add the ROLE_JMX role to the user in users.xml, and also the ROLE_USER role if it is required to provide access to the Web UI. (Also see Assigning User Permissions).

Make sure ${OPENNMS_HOME}/etc/jmxremote.access has the appropriate settings:

admin   readwrite
jmx     readonly

The possible types of access are:

readwrite

Lets you retrieve JMX metrics as well as executing MBeans.

readonly

Lets you retrieve JMX metrics but does not allow executing MBeans, even if they just return simple values.

Enabling SSL

To enable SSL on the RMI port, you will need to have an existing keystore for the Meridian server. For information on configuring a keystore, see How to setup SSL with Jetty.

You will need to change the com.sun.management.jmxremote.ssl option to true, and tell Meridian where your keystore is.

# Configure remote JMX
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.port=18980"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.local.only=false"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.authenticate=true"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.ssl=true"

# Configure SSL Keystore
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Djavax.net.ssl.keyStore=/opt/opennms/etc/opennms.keystore"
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Djavax.net.ssl.keyStorePassword=changeit"

# Listen on all interfaces
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dopennms.poller.server.serverHost=0.0.0.0"
# Accept remote RMI connections on this interface
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Djava.rmi.server.hostname=<your-server-ip-address>"

Connecting to RMI over SSL

Note that if you use a self-signed or otherwise untrusted certificate, you must configure a truststore on the client side when you attempt to connect over SSL-enabled RMI. To create a truststore, follow the example in the HTTPS client instructions. You may then use the truststore to connect to your Meridian RMI server.

For example, when using jconsole to connect to the Meridian RMI interface to get JVM statistics, you would run:

jconsole -J-Djavax.net.ssl.trustStore=/path/to/opennms.truststore -J-Djavax.net.ssl.trustStorePassword=changeit