Enable Event Distribution
Steps
Turn remote observation on, on every node of a cluster, so that each node also applies what the others did.
- In xwiki.properties, enable remote observation. It is off by default, so this is the one line every node needs.
observation.remote.enabled = true - Name the node in the same file. Without it XWiki generates a UUID and stores it in the observation/id.txt file of that node's permanent directory, and every later diagnostic reads as that UUID instead of a name.
observation.remote.id = node1 - Choose a channel and list it in observation.remote.channels. The value is the base name of a JGroups configuration file, and XWiki ships none of its own: start with udp, which comes from inside the JGroups library and finds the other nodes by multicast. The property is empty by default, so until it names a channel an enabled node still distributes nothing.
observation.remote.channels = udp - If multicast is blocked on your network, use tcp instead, and list the members yourself. This is the step that is easy to miss: jgroups.tcpping.initial_hosts defaults to localhost[7800], so a node that does not get the list only ever finds itself, and the cluster stays silent without any error.
observation.remote.channels = tcpPass the member list to the JVM of every node:
-Djgroups.tcpping.initial_hosts=node1.example.org[7800],node2.example.org[7800] - Write your own channel file only if the stacks JGroups bundles do not fit. Drop an XML file into the node's WEB-INF/observation/remote/jgroups/ directory, name it after the channel, and list that name in observation.remote.channels. The jgroups network adaptor that reads it is the default of observation.remote.networkadapter, and Cluster Architecture says when another one would apply.
WEB-INF/observation/remote/jgroups/mycluster.xmlThe JGroups manual documents what goes inside such a file.
- Tell JGroups which network to use when the host has more than one interface, or runs IPv6. JGroups picks an interface by matching the ones it finds, which on a multi-homed server is not always the one the other nodes can reach; and on IPv6 the multicast address and the preferred IP stack have to be of the same family, so forcing IPv4 is the simplest way to be sure.
-Djgroups.bind_addr=10.0.0.11 -Djava.net.preferIPv4Stack=true - Restart every node, and look for its channel in the log.
INFO jgroups.JGroupsNetworkAdapter - Channel [udp] startedEach node now applies the events the others emit. Verify a Cluster proves the nodes really see each other, and Shared Resources lists what they still have to share.
FAQ
Is the channel name what groups the nodes together?
No. The name only selects the configuration file, because XWiki always connects to the same JGroups cluster, called event. What decides which nodes end up in one group is the transport that file configures: the jgroups.udp.mcast_addr (239.8.8.8 by default) and jgroups.udp.mcast_port (45588) system properties for udp, the member list for tcp. Two groups that must stay independent therefore need settings of their own there, not merely different file names, and one file describes one group, so a node that belongs to both needs a file for each and lists both names in observation.remote.channels, separated by a comma.
