Relates :
|
|
Relates :
|
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