JEP 168: Network Discovery of Manageable Java Processes
|Discussion||serviceability dash dev at openjdk dot java dot net|
|Reviewed by||Mikael Vidstedt|
|Endorsed by||Mikael Vidstedt|
Define a lightweight network protocol for discovering running and manageable Java processes within a network subnet.
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.
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.
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
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 it's 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
ticket [IANA #656814]:
188.8.131.52 JDP Java Discovery Protocol
ticket [IANA #656816]
Unit tests will be provided.
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