Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8046158

JEP 168: Network Discovery of Manageable Java Processes

    XMLWordPrintable

    Details

    • Type: JEP
    • Status: Closed
    • Priority: P4
    • Resolution: Delivered
    • Fix Version/s: 8
    • Component/s: core-svc
    • Labels:
      None
    • Author:
      Dmitry Samersoff
    • JEP Type:
      Feature
    • Exposure:
      Open
    • Scope:
      JDK
    • Discussion:
      serviceability dash dev at openjdk dot java dot net
    • Effort:
      M
    • Duration:
      M
    • Alert Status:
       Green
    • JEP Number:
      168

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              dsamersoff Dmitriy Samersoff
              Reporter:
              dsamersoff Dmitriy Samersoff
              Owner:
              Dmitriy Samersoff Dmitriy Samersoff
              Reviewed By:
              Mikael Vidstedt
              Endorsed By:
              Mikael Vidstedt
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: