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 stopsMAIN_CLASS
-- The value of thesun.java.command
propertyJMX_SERVICE_URL
-- The URL to connect to the JMX agentINSTANCE_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 portcom.sun.management.jdp.address
-- override default addresscom.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 1com.sun.management.jdp.pause
-- set broadcast interval in seconds default is 5com.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
- relates to
-
JDK-8002048 Protocol for discovery of manageable Java processes on a network
-
- Resolved
-
-
JDK-8069071 Document Java Discovery Protocol
-
- Resolved
-