| = MultiPulse (UDP) Discovery |
| :index-group: Discovery and Failover |
| :jbake-date: 2018-12-05 |
| :jbake-type: page |
| :jbake-status: published |
| |
| |
| MultiPulse is an alternative multicast lookup that does not use a |
| regular heartbeat. Instead, servers listen for a multicast request |
| packet (a pulse) to which a response is then sent. Multicast network |
| traffic is effectively reduced to an absolute minimum. |
| |
| MultiPulse is only useful in network scenarios where both client and |
| server can be configured to send multicast UDP packets. |
| |
| == Server Configuration |
| |
| After you boot the server for the first time the default configuration |
| will create the file `conf/conf.d/multipulse.properties` containing: |
| |
| [source,properties] |
| ---- |
| server = org.apache.openejb.server.discovery.MulticastPulseAgent |
| bind = 239.255.2.3 |
| port = 6142 |
| disabled = true |
| group = default |
| ---- |
| |
| You just need to enable the agent by setting `disabled = false`. It is |
| advisable to disable multicast in the `multicast.properties file`, or at |
| least to use a different bind address or port should you wish to use |
| both. |
| |
| All of the above settings except `server` can be modified as required. |
| The `port` and `bind` must be valid for general multicast/udp network |
| communication. |
| |
| The `group` setting can be changed to further group/cluster servers that |
| may use the same multicast channel. As shown below the client also has |
| an optional `group` setting which can be used to select an appropriate |
| server cluster from the multicast channel (See MultiPulse Client). |
| |
| The next step is to ensure that the advertised services are configured |
| for discovery. Edit the `ejbd.properties` file (and any other enabled |
| services such as http, etc.) and ensure that the `discovery` option is |
| set to a value that remote clients will be able to resolve. |
| |
| [source,properties] |
| ---- |
| server = org.apache.openejb.server.ejbd.EjbServer |
| bind = 0.0.0.0 |
| port = 4201 |
| disabled = false |
| threads = 20 |
| discovery = ejb:ejbd://{bind}:{port} |
| ---- |
| |
| NOTE: If either `0.0.0.0` (IPv4) or `[::]` (IPv6) wildcard bind |
| addresses are used then the server will actually broadcast all of it's |
| known public hosts to clients. Clients will then cycle though and |
| attempt to connect to the provided hosts until successful. |
| |
| If `localhost` is used then only clients on the same physical machine |
| will actually 'see' the server response. |
| |
| == MultiPulse Client |
| |
| The multipulse functionality is not just for servers to find each other |
| in a cluster, it can also be used for EJB clients to discover a server. |
| A special `multipulse://` URL can be used in the `InitialContext` |
| properties to signify that multipulse should be used to seed the |
| connection process. Such as: |
| |
| [source,java] |
| ---- |
| Properties p = new Properties(); |
| p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory"); |
| p.put(Context.PROVIDER_URL, "multipulse://239.255.2.3:6142?group=default&timeout=250"); |
| InitialContext remoteContext = new InitialContext(p); |
| ---- |
| |
| The URL has optional query parameters such as `schemes` and `group` and |
| `timeout` which allow you to zero in on a particular type of service of |
| a particular cluster group as well as set how long you are willing to |
| wait in the discovery process till finally giving up. The first matching |
| service that it sees "flowing" around on the UDP stream is the one it |
| picks and sticks to for that and subsequent requests, ensuring UDP is |
| only used when there are no other servers to talk to. |
| |
| Note that EJB clients do not need to use multipulse to find a server. If |
| the client knows the URL of a server in the cluster, it may use it and |
| connect directly to that server, at which point that server will share |
| the full list of its peers. |
| |
| == Multicast Servers with TCP Clients |
| |
| Note that clients do not need to use multipulse to communicate with |
| servers. Servers can use multicast to discover each other, but clients |
| are still free to connect to servers in the network using the server's |
| TCP address. |
| |
| [source,java] |
| ---- |
| Properties p = new Properties(); |
| p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory"); |
| p.put(Context.PROVIDER_URL, "ejbd://192.168.1.30:4201"); |
| InitialContext remoteContext = new InitialContext(p); |
| ---- |
| |
| When the client connects, the server will send the URLs of all the |
| servers in the group and failover will take place normally. |