Multicast Discovery of Agents

[rhuss]

It should be possible to (a) allow agents to respond to multicast requests for their URL and (b) triggering an MBean operation for finding all agents with a multi cast request.

See #125 for more details and an alternative approach.

Currently, most of the stuff is already implemented and can be tried out with the 1.2.0-SNAPSHOT where the discovery mechanism is enabled by default (for the WAR agent it has to be enabled by an ini param or a system property). The MBean can be found at jolokia:type=Discovery.

More documentation to follow, I also have still some points to discuss (but now I'm too tired ;-).

[rhuss]

I'll put the documentation draft in this issue which finally will make it into the reference manual

Agent Discovery

Jolokia agents are able to respond to certain multicast requests in order to allow clients to detect automatically connection parameters. The agent URL to expose can be either manually configured for an agent or an agent can try to detect its URL automatically. This works fine for the JVM agent, for the WAR agent it only works after the first HTTP request has been processed by the agent. Due to limitations of the Servlet API the agent servlet has no clue about its own URL until this first request, which contains the request URL. Of course, the URL obtained that way can be bogus as well, since the agent might hide behind a proxy, too. So, if in doubt you should configure the agent URL from outside to allow external clients to be discovered.

A agent which is enabled for multicast discovery will only respond to a multicast request if the restrictor allows connections from the source IP. Otherwise a multicast request will be simply ignored. For example, if you have configured your agent to only allow request from a central monitoring host, only this host is able to detect these agents. Beside security aspects it wouldn't make sense to expose the URL as any other host is not able to connect anyways.

Starting with version 1.2.0 the Jolokia JVM agent has this discovery feature enabled by default which can be switched off via --discoveryDisabled command line parameter or the corresponding configuration option. For the WAR agent and OSGi agents this feature is switched off by default since auto detection doesn't work always. It can be enabled with the init parameter discoveryEnabled (in which case the auto discovery described above is enabled) or better with discoveryAgentUrl with the URL. Alternatively, a system property can be used with a jolokia. prefix (e.g. jolokia.discoveryEnabled). More on the configuration options can be found in the agent's configuration sections.

Multicast Discovery Protocol

For sending a multicast request discovery message, an UDP message should be send to the address 239.192.48.84, port 24884 which contains a JSON message encoded in UTF-8 with the following format

{
    "type": "query"
}

Any agent enabled for disovery will respond to requestor on the same socket with an answer which looks like

{
    "type": "response",
    "agent_description" : "Atlantis Tomcat",
    "agent_id" : "10.9.11.18-58613-81b087d-servlet",
    "url": "http://10.9.11.25:8778/jolokia",
    "confidence": 100,
    "server_vendor" : "Apache", 
    "server_product" : "Tomcat",
    "server_version" : "7.0.35"
}

Please note, that the format with respect to url, confidence is still under discussion. It could be that, confidence will be removed since it doesn't make much sense anyways or the URLs will be put into a list for multiples suggestions to try if the URL couldn't be determined for sure. Any opinions ?

The response is restricted to 8192 bytes maximum. IPv6 is currently not supported yet but likely in the future.

Discovery MBean

Every agent registers an MBean at jolokia:type=Discovery regardless whether multicast discovery is enabled or not. This MBean has a single operation lookupAgents. This operation multicasts a discovery request to the network and collects the responses which then is returned as an JSON arrays containing the details of every response. A sample return value of this JMX operation looks like

[
  {
      "agent_id" : "10.9.11.18-58613-81b087d-servlet",
      "url": "http://10.9.11.25:8778/jolokia",
      "secured": false,
      "server_vendor" : "Apache", 
      "server_product" : "Tomcat",
      "server_version" : "7.0.35"
  },
  {
      "agent_id" : "10.9.11.87-23455-9184ef-osgi",
      "agent_description": "My OSGi container",
      "url": "http://10.9.11.87:8080/jolokia",
      "secured": true,
      "server_vendor" : "Apache", 
      "server_product" : "Felix",
      "server_version" : "4.2.1"
  }
]

[rhuss]

Long done.