JEP 168: Network Discovery of Manageable Java Processes

Summary

Define a lightweight network protocol for discovering running and manageable Java processes within a network subnet.

Goals

• A simple service that does not have dependencies on anything other than what is in the JDK.

• A service that does not require any process other than the Java process to run.

• It must be able to provide information about a running Java process on the network, and it must be possible to detect when the Java process is no longer running.

• It must not require prior knowledge about what machines are available on the network.

• It must include information about the endpoint of communication, such as the JMXService URL.

• The service should be stopped when we stop the management agent and it should not be possible to start the service without the management agent.

• It should contain other information useful for rendering the connection in a client, such as PID, JRE version, and main class.

• It should be possible to extend the information broadcasted.

Non-Goals

• The protocol is not intended to be used across a public network.

• The protocol doesn't offer any access control; that should be done in the network layer.

Description

The protocol is lightweight multicast based, and works like a beacon, broadcasting the JMXService URL needed to connect to the external JMX agent if an application is started with appropriate parameters.

The payload is structured like this:

4 bytes JDP magic (0xC0FFEE42)
2 bytes JDP protocol version (1)
2 bytes	size of the next entry
    x bytes next entry (UTF-8 encoded)
    2 bytes size of next entry
...	Rinse and repeat...

The payload will be parsed as even entries being keys, odd entries being values.

The standard JDP packet contains four entries:

• DISCOVERABLE_SESSION_UUID -- Unique id of the instance; this id changes every time the discovery protocol starts and stops

• MAIN_CLASS -- The value of the sun.java.command property

• JMX_SERVICE_URL -- The URL to connect to the JMX agent

• INSTANCE_NAME -- The user-provided name of the running instance

The protocol uses system properties to control its behaviour:

• com.sun.management.jdp.port -- override default port

• com.sun.management.jdp.address -- override default address

• com.sun.management.jmxremote.autodiscovery -- whether we should start autodiscovery or not. Autodiscovery starts if and only if following conditions are met: (autodiscovery is true OR (autodiscovery is not set AND jdp.port is set))

• com.sun.management.jdp.ttl -- set ttl for broadcast packet, default is 1

• com.sun.management.jdp.pause -- set broadcast interval in seconds default is 5

• com.sun.management.jdp.source_addr -- an address of interface to use for broadcast

Default values

ticket [IANA #656814]:

224.0.23.178 JDP Java Discovery Protocol

ticket [IANA #656816]

7095/UDP

Testing

Unit tests will be provided.

Impact

• Other JDK components: Will only impact the JMX Agent

• Compatibility: No impact

• Security: The protocol is off by default, also the default TTL for multicast packets is set to zero so the packet will not escape a local network.

• Performance/scalability: Limited impact, one extra thread

• User experience: No impact

• I18n/L10n: No impact

• Accessibility: No impact

• Portability: No impact

• Packaging/installation: No impact

• Documentation: The new options and their usage will have to be documented.

• TCK: No impact