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

JEP 168: Network Discovery of Manageable Java Processes

XMLWordPrintable

    • Icon: JEP JEP
    • Resolution: Delivered
    • Icon: P4 P4
    • 8
    • core-svc
    • None
    • Dmitry Samersoff
    • Feature
    • Open
    • JDK
    • serviceability dash dev at openjdk dot java dot net
    • M
    • M
    • 168

      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

            dsamersoff Dmitriy Samersoff
            dsamersoff Dmitriy Samersoff
            Dmitriy Samersoff Dmitriy Samersoff
            Mikael Vidstedt
            Mikael Vidstedt
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: