
= Enable RMI
:description: Learn how to enable the RMI port in {page-component-title} to let you access Horizon/Meridian via jconsole and remotely manage your instance.

By default, the {page-component-title} server's RMI port is disabled for security reasons.
When enabled, it lets you access {page-component-title} via `jconsole` and remotely manage your instance.

To enable RMI, you must add some settings to the default {page-component-title} installation.
Add the following code to `$\{OPENNMS_HOME}/etc/opennms.conf`:

[source, properties]
----
# Configure remote JMX
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Dcom.sun.management.jmxremote.port=18980" <1>
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" <2>
# Accept remote RMI connections on this interface
ADDITIONAL_MANAGER_OPTIONS="$ADDITIONAL_MANAGER_OPTIONS -Djava.rmi.server.hostname=<your-server-ip-address>" <3>
----
<1> Configures {page-component-title} to listen for RMI on port `18980`.
<2> Configures {page-component-title} to listen for RMI on all interfaces.
Note that originally, RMI was used only for the legacy remote poller; despite this property name mentioning the "OpenNMS poller server," it applies to RMI as a whole.
<3> Allows {page-component-title} to accept and complete RMI connections.
You must include this option, otherwise {page-component-title} will accept connections but will not be able to complete a valid connection.

NOTE: If `$\{OPENNMS_HOME}/etc/opennms.conf` does not exist in your install, you can create it and add the code above.

== Allow user authentication

Authentication is allowed only for users who are assigned the `admin` or `jmx` roles (`ROLE_ADMIN`, `ROLE_JMX`).
To assign the `admin` role to a user, add `ROLE_ADMIN` to their entry in `users.xml`.
Similarly, to assign the `jmx` role to a user, add `ROLE_JMX` to their entry in `users.xml`.

If the `ROLE_USER` role is required to allow access to the web UI, ensure that the user's account has it as well (see xref:deep-dive/user-management/security-roles.adoc[]).

You should also ensure that `$\{OPENNMS_HOME}/etc/jmxremote.access` has the appropriate access settings for each role:

[source, properties]
----
admin   readwrite
jmx     readonly
----

The following types of access are available in {page-component-title}:

* `readwrite`: Lets a user retrieve JMX metrics and run MBeans.
* `readonly`: Lets a user retrieve JMX metrics, but does not allow them to run MBeans.

== Enable SSL

To enable SSL on the RMI port, you need an existing keystore for your {page-component-title} server.
For information on configuring a keystore, see xref:deep-dive/admin/configuration/https/https-server.adoc[].

After your keystore is set up and configured, you must change the `com.sun.management.jmxremote.ssl` to `true` and tell {page-component-title} where your keystore is:

[source, properties]
----
# 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"
----

=== Connect to RMI over SSL

Note that if you use a self-signed or otherwise untrusted certificate, you must configure a client-side truststore when you try to connect over SSL-enabled RMI.
For information on creating and configuring a truststore, see xref:deep-dive/admin/configuration/https/https-server.adoc[].

After you set up a truststore, you may use it to connect to your {page-component-title} RMI server.
For example, when using `jconsole` to connect to the {page-component-title} RMI interface, run the following command to retrieve JVM statistics:

[source, console]
jconsole -J-Djavax.net.ssl.trustStore=/path/to/opennms.truststore -J-Djavax.net.ssl.trustStorePassword=changeit
