java org.jgroups.Version
Version: 2.2.8 RC1
CVS: $Id: INSTALL.html,v 1.11 2009/12/02 13:00:10 belaban Exp $
History: (see doc/history.txt for details)
By default, we're running 2 senders with 10000 1K messages each, to do this, execute the following in 2 shells:
./jgroups.sh tests.perf.Test -config ./config.txt -props ./udp.xml -sender
-- results:
192.168.5.2:4301 (myself):
num_msgs_expected=20000, num_msgs_received=20000 (loss rate=0.0%), received=20MB, time=3750ms, msgs/sec=5333.33, throughput=5.33MB
192.168.5.2:4311:
num_msgs_expected=20000, num_msgs_received=20000 (loss rate=0.0%), received=20MB, time=3750ms, msgs/sec=5333.33, throughput=5.33MB
combined: 5333.33 msgs/sec averaged over all receivers (throughput=5.33MB/sec)
./jgroups.sh demos.Drawtwice (use jgroups.bat on Windows). 2 whiteboard windows should appear. If you started them simultaneously, they should initially show a membership of 1 in their title bars. After some time, both windows should show 2. This means that the two instances found each other and formed a group.
When drawing in one window, the second instance should also be updated. As the default group transport uses IP multicast, make sure that - if you want to start the 2 instances in different subnets - IP multicast is enabled. If this is not the case, the 2 instances won't 'find' each other and the sample won't work.
You can change the properties of the demo to for example use a different transport if multicast doesn't work (it should always work on the same machine). For example, to use udp.xml, execute:
./jgroups.sh demos.Draw -props ./udp.xml
route add -net 224.0.0.0 netmask 224.0.0.0 dev loThis means that all traffic directed to the 224.0.0.0 network will be sent to the loopback interface, which means it doesn't need any network to be running. Note that the 224.0.0.0 network is a placeholder for all multicast addresses in most UNIX implementations: it will catch all multicast traffic. This is an undocumented feature of /sbin/route and may not work across all UNIX flavors. The above instructions may also work for Windows systems, but this hasn't been tested. Note that not all systems allow multicast traffic to use the loopback interface.
Typical home networks have a gateway/firewall with 2 NICs: the first
(eth0) is connected to the outside world (Internet Service Provider),
the second (eth1) to the internal network, with the gateway
firewalling/masquerading traffic between the internal and external
networks. If no route for multicast traffic is added, the default will
be to use the fdefault gateway, which will typically direct the
multicast traffic towards the ISP. To prevent
this (e.g. ISP drops multicast traffic, or latency is too high), we
recommend to add a route for multicast traffic which goes to the
internal network
(e.g. eth1).
./jgroups.sh tests.McastReceiverTest -mcast_addr 224.10.10.10 -port 5555Then start McastSenderTest:
./jgroups.sh tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555You should be able to type in the McastSenderTest window and see the output in the McastReceiverWindow. If not, try to use -ttl 32 in the sender. If this still fails, consult a system administrator to help you setup IP multicast correctly. If you are the system administrator, look for another job :-)
Other means of getting help: there is a public forum on JIRA for questions. Also consider subscribing to the javagroups-users mailing list to discuss such and other problems.
In this case we have to use a sledgehammer (running only under JDK 1.4. and higher): we can enable the above sender and receiver test to use all available interfaces for sending and receiving. One of them will certainly be the right one... Start the receiver as follows:
java org.jgroups.tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces
The multicast receiver uses the 1.4 functionality to list all
available network interfaces and bind to all of them (including
the loopback interface). This means that whichever interface a packet
comes in on, we
will receive it.
Now start the sender:
./jgroups.sh tests.McastSenderTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces
The sender will also determine the available network interfaces and send each packet over all interfaces.
This test can be used to find out which network interface to bind to when previously no packets were received. E.g. when you see the following output in the receiver:
bash-2.03$ ./jgroups.sh tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -bind_addr 192.168.168.4
Socket=0.0.0.0/0.0.0.0:5555, bind interface=/192.168.168.4
dd [sender=192.168.168.4:5555]
dd [sender=192.168.168.1:5555]
dd [sender=192.168.168.2:5555]
you know that you can bind to any of the 192.168.168.{1,2,4} interfaces to receive your multicast packets. In this case you would need to modify your protocol spec to include bind_addr=192.168.168.2 in UDP, e.g. "UDP(mcast_addr=228.8.8.8;bind_addr=192.168.168.2):..." .
Alternatively you can use McastDiscovery1_4 (runs only on JDK 1.4).
Start this program simultaneously on multiple machines. Binding to all
available interfaces, this program tries to discover what other members
are available in a network and determines which interfaces should be
used by UDP. After some time (e.g. 30 seconds), press <enter> on
each program. The program will then list the interfaces which can be
used to bind to. There may be
one or multiple interfaces. When there are multiple interfaces listed,
take
the one with the highest number of responses (at the top of the list).
The
UDP protocol spec can then be changed to explicitly bind to that
interface,
e.g.
"UDP(bind_addr=<interface>;...)"
Another source of problems might be the use of IPv6, and/or
misconfiguration
of /etc/hosts. If you communicate between an IPv4 and an IPv6
host,
and they are not able to find each other, try the java.net.preferIP4Stack=true
property, e.g.
java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw
-props
file:c:\\udp.xml
JDK 1.4.1 uses IPv6 by default, although is has a dual stack, that
is,
it also supports IPv4. Here's more
details on the subject.