Skip to main content
Version: 10.3.2

Configure remote JMX attachment for Java applications

The primary purpose of the remote attachment functionality is to attach to a target Java process running on the same physical machine and upload a JVM agent that exposes the user interface (UI) structure of the target application when the local attachment mechanism is explicitly disabled, for example, when the application is started with the -XX:+DisableAttachMechanism property. Thus, you can navigate and automate Java-based UIs, such as applets.

This functionality allows the Worker to use a remote attachment mechanism, where authentication, SSL, and other remote JMX-specific parameters are applied when the target application blocks the local attachment mechanism.

Supported versions​

Remote attachment supports target applications running on the following Java Development Kit (JDK) long-term support (LTS) versions:

  • Java 8

  • Java 11

  • Java 17

  • Java 21

The Worker application runs on JDK 21.

Configuration​

To activate the mechanism, the following properties must be set.

The properties on the target application side are as follows:

  • -Dcom.sun.management.jmxremote: enables the built-in JMX management agent when the target application Java virtual machine (JVM) starts.

  • -Dcom.sun.management.jmxremote.port=<port>: the TCP port on which the JMX RMI registry listens for incoming connections.

  • -Dcom.sun.management.jmxremote.rmi.port=<port>: the TCP port used by the JMX RMI server itself for remote method calls. By default, a random ephemeral port is chosen.

  • -Djava.rmi.server.hostname=<host>: the advertised hostname that clients (the Worker) use to connect. The default value is 127.0.0.1.

  • -javaagent:/path/to/rpa-jvmagent.jar: loads a Java agent JAR at target application JVM startup. The option must be used when -XX:+DisableAttachMechanism is applied.

    The path to rpa-jvmagent.jar depends on the target application's Java version: RPA/rpa-grid/dependency/" + jvmVersion + "/rpa-jvmagent.jar.

    • Java 8: RPA/rpa-grid/dependency/java8/rpa-jvmagent.jar

    • Java 11 or Java 17: RPA/rpa-grid/dependency/java11/rpa-jvmagent.jar

    • Java 21: RPA/rpa-grid/dependency/java21/rpa-jvmagent.jar

  • -Dcom.sun.management.jmxremote.ssl=false: disables SSL encryption for JMX connections, allowing plain-text communication. The default value is false.

If your target application has authentication enabled, specify the following properties:

  • -Dcom.sun.management.jmxremote.authenticate=true

  • -Dcom.sun.management.jmxremote.login.config=jmx_auth

  • -Djava.security.auth.login.config=<path/to/jaas.config

  • -Dcom.sun.management.jmxremote.access.file=path/to/jmxremote.access

On the Worker side, define the following settings:

  • -Drpa.jvm.connector.remote=true: forces the Worker to use the remote JMX attachment mechanism.

  • -Djmx.remote.host=<host>: the target application's remote JMX host; must match the value of Djava.rmi.server.hostname on the target application side. The default value is 127.0.0.1.

  • -Djmx.remote.port=9999: the target application's remote JMX port; must match the value of com.sun.management.jmxremote.port on the target application side. The default value is 9999.

  • -Djmx.remote.credentials=path\\to\\creadentials\\filename.ps1: the path to a .ps1 file that returns credentials for JMX authentication. The script must return a map in the following format: { "username":"<username>", "password":"<password>"}

Examples​

The target application start command is as follows:

java -XX:+DisableAttachMechanism ^
     -Dcom.sun.management.jmxremote ^
     -Dcom.sun.management.jmxremote.port=9999 ^
     -Dcom.sun.management.jmxremote.rmi.port=9010 ^
     -Djava.rmi.server.hostname=127.0.0.1 ^
     -Dcom.sun.management.jmxremote.authenticate=true ^
     -Dcom.sun.management.jmxremote.login.config=jmx_auth ^
     -Djava.security.auth.login.config=C:/RPA/tools/jaas.config ^
     -Dcom.sun.management.jmxremote.access.file=C:/RPA/tools/jmxremote.access ^
     -Dcom.sun.management.jmxremote.ssl=false ^
     -javaagent:C:/RPA/rpa-grid/dependency/java8/rpa-jvmagent.jar ^
     -jar MyApp.jar

The Worker extra properties are shown below:

-Drpa.jvm.connector.remote=true ^ 
-Djmx.remote.host=127.0.0.1 ^ 
-Djmx.remote.port=9999 ^ 
-Djmx.remote.credentials=C:\\install\\jmx-apps\\jmx-creds.ps1 ^