# Activating a component's JMX interface

This page describes how to enable Java Management Extensions (JMX) monitoring for Liberator, Transformer, and other DataSources.

## Overview

The Caplin Management Console (CMC) connects to monitorable components via Java Remote Method Invocation (RMI).

By default, a DataSource’s RMI interface is not enabled and so the DataSource is not available for monitoring. To activate a DataSource’s RMI interface, you define values for the configuration items [rmi-registry-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-registry-port) and [rmi-client-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-client-port).

How you define values for [rmi-registry-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-registry-port) and [rmi-client-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-client-port) differs between DataSources. Some DataSources require you to set these configuration items indirectly via macro definitions; other require you to set the configuration items directly.

## Activating JMX in Liberator

Liberator’s JMX interface is not activated by default. Follow the steps below to activate it:

1. Run the command below to stop Liberator:

   ```console
   $ ./dfw stop Liberator
   ```
2. Run the command below to activate the LiberatorJMX blade:

   ```console
   $ ./dfw activate LiberatorJMX
   ```
3. In the file `global_config/environment.conf`, set Liberator’s Java RMI hostname to the hostname or IP address of Liberator’s host:

   ```
   define LIBERATOR${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME       <hostname>
   ```

   **❗ IMPORTANT**\
   If you do not set a Java RMI hostname, Java RMI attempts to detect the hostname automatically. In practice, this can often mean the hostname defaults to 'localhost', which causes connectivity problems when CMC is run on a different host to Liberator.
4. Liberator’s JMX registry port and client port default to `${THIS_LEG}1001` and `${THIS_LEG}2001` respectively. To override these defaults, redefine the following variables in the Deployment Framework file `global_config/environment.conf`:

   ```
   define LIBERATOR${THIS_LEG}_JMX_RMI_REGISTRY_PORT         ${THIS_LEG}1001
   define LIBERATOR${THIS_LEG}_JMX_RMI_CLIENT_PORT           ${THIS_LEG}2001
   ```
5. Liberator’s JMX interface is password protected, and the username and password default to `admin` and `admin` respectively. To override these defaults, redefine the following variables in the Deployment Framework file `global_config/environment.conf`:

   ```
   define LIBERATOR_MONUSER    admin
   define LIBERATOR_MONPASS    admin
   ```
6. Run the command below to restart Liberator:

   ```console
   $ ./dfw start Liberator
   ```

## Activating JMX in Transformer

Transformer’s JMX interface is not enabled by default. Follow the steps below to activate it:

1. Run the command below to stop Transformer:

   ```console
   $ ./dfw stop Transformer
   ```
2. Run the Deployment Framework command below to activate the TransformerJMX blade:

   ```console
   $ ./dfw activate TransformerJMX
   ```
3. In the file `global_config/environment.conf`, set Transformer’s Java RMI hostname to the hostname or IP address of Transformer’s host:

   ```
   define TRANSFORMER${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME       <hostname>
   ```

   **❗ IMPORTANT**\
   If you do not set a Java RMI hostname, Java RMI attempts to detect the hostname automatically. In practice, this can often mean the hostname defaults to 'localhost', which causes connectivity problems when CMC is run on a different host to Transformer.
4. Transformer’s JMX registry port and client port default to `${THIS_LEG}1002` and `${THIS_LEG}2002` respectively. To override these defaults, redefine the following variables in the Deployment Framework file `global_config/environment.conf`:

   ```
   define TRANSFORMER${THIS_LEG}_JMX_RMI_REGISTRY_PORT         ${THIS_LEG}1002
   define TRANSFORMER${THIS_LEG}_JMX_RMI_CLIENT_PORT           ${THIS_LEG}2002
   ```
5. Transformer’s JMX interface is password protected, and the username and password default to `admin` and `admin` respectively. To override these defaults, redefine the following variables in the Deployment Framework file `global_config/environment.conf`:

   ```
   define TRANSFORMER_MONUSER    admin
   define TRANSFORMER_MONPASS    admin
   ```
6. Run the command below to restart Transformer:

   ```console
   $ ./dfw start Transformer
   ```

## Activating JMX in a C DataSource (with feature blades)

This section applies to C DataSource adapters with a JMX feature blade ([TREP Adapter](../../trep-adapter/index.md)) that have been deployed to a Deployment Framework. For C DataSource adapters without a JMX feature blade, or for C DataSource adapters deployed outside of a Deployment Framework, see [Activating JMX in a C DataSource (without feature blades)](#activating-jmx-in-a-c-datasource-without-feature-blades).

The steps for enabling the JMX interface of the above adapters are similar to the steps for enabling the JMX interfaces of Liberator and Transformer.

For example, to enable the JMX interface of a Caplin TREP adapter in a Deployment Framework, follow the steps below:

1. Stop the adapter:

   ```console
   $ ./dfw stop TREPAdapter
   ```
2. Activate the JMX blade for the adapter:

   ```console
   $ ./dfw activate TREPAdapterJMX
   ```
3. To change the TREP adapter’s default RMI settings, edit the file `global_config/overrides/TREPAdapter/DataSource/etc/environment.conf`, and change the values assigned to the following [configuration variables](../datasource/datasource-configuration-syntax.md):

   ```
   define TREPAdapter${THIS_LEG}_JMX_RMI_REGISTRY_PORT    __value__
   define TREPAdapter${THIS_LEG}_JMX_RMI_CLIENT_PORT      __value__
   define TREPAdapter${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME  __value__
   ```

   For more information on the meaning of the three configuration variables above, see the documentation for [rmi-registry-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-registry-port), [rmi-client-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-client-port), and [Oracle Java: java.rmi system properties](https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/javarmiproperties.html).
4. Restart the adapter:

   ```console
   $ ./dfw start TREPAdapter
   ```

## Activating JMX in a C DataSource (without feature blades)

To enable the JMX interface of a C DataSource adapter that does not include a JMX configuration blade, or to enable the JMX interface of a C DataSource adapter deployed outside of a Deployment Framework, add the following configuration items to the adapter’s `etc/jmx.conf` file:

**File: etc/jmx.conf**

```
# RMI registry port
rmi-registry-port <port>

# RMI client port
rmi-client-port <port>

# Hostname remote JMX clients should use to connect to this server
jvm-options -Djava.rmi.server.hostname=<hostname>
```

For more information on the configuration items above, see the links below:

* [rmi-registry-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-registry-port)
* [rmi-client-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-client-port)
* [jvm-options](../datasource/datasource-java-jvm-configuration.md#jvm-options)
* [Oracle Java: java.rmi system properties](https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/javarmiproperties.html)

## Activating JMX in a Java DataSource

To enable the JMX interface of a Java DataSource, add the following lines to the file `global_config/overrides/__bladename__/etc/datasource.conf`:

```
# RMI registry port
rmi-registry-port <port>

# RMI client port
rmi-client-port <port>

add-monuser
    user    admin
    pass    admin
end-monuser
```

Add the JMX hostname to the script used by the Deployment Framework to run the Java DataSource: `kits/__bladename__/__bladename__-__version__/DataSource/bin/start-jar.sh`. This script varies between DataSources; the example script below is taken from Caplin’s Pricing Adapter Template (see [start-jar.sh](https://github.com/caplin/project-templates/blob/master/pricing-template/blade/DataSource/bin/start-jar.sh)):

```bash
#!/bin/bash
#
# Start the Pricing Template Java Adapter.
#
# $1 - Path to java executable
# $2 - Path to datasource XML file
# $3 - Path to fields XML file
# $4 - Java definitions ( optional )
#
# Returns the process id of the Java process.
#

BLADENAME=MyPricingAdapter5

if [ "$1" = "CONFREADER" ]; then
   shift
   confreading=1
   jar=`ls "$BINARY_ROOT"/lib/datasource*.jar|head -1`
else
   confreading=0
   jar=`ls "$BINARY_ROOT"/lib/$BLADENAME*.jar|head -1`
   classpath="${BINARY_ROOT}/lib/*"

   echo "Classpath: $jar"
fi

if [ $confreading = 1 ]; then
   java -jar "$jar" "$@"
   exit $?
else
   java \ ①
    -Djava.rmi.server.hostname=<hostname>
    -cp "$classpath" \
    -jar "$jar" "$@" 2> "$LOGDIR"/java-$BLADENAME.log >/dev/null &
   echo $!
fi
```
1. Original command split onto multiple lines for clarity

For more information on the configuration items above, see the links below:

* [rmi-registry-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-registry-port)
* [rmi-client-port](../datasource/datasource-datasource-monitoring-configuration-part-1.md#rmi-client-port)
* [Oracle Java: java.rmi system properties](https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/javarmiproperties.html)