| 1 |
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> |
| 2 |
<html> |
| 3 |
<head> |
| 4 |
<meta http-equiv="Content-Type" |
| 5 |
content="text/html; charset=iso-8859-1"> |
| 6 |
<meta name="GENERATOR" |
| 7 |
content="Mozilla/4.61 [en] (X11; U; SunOS 5.8 sun4u) [Netscape]"> |
| 8 |
<title>JGroups 2.8.x Installation</title> |
| 9 |
<link rel="STYLESHEET" href="../user.css"> |
| 10 |
</head> |
| 11 |
<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000" |
| 12 |
vlink="#551a8b"> |
| 13 |
<comment> </comment> |
| 14 |
<h1> Installation Instructions for JGroups<br> |
| 15 |
</h1> |
| 16 |
JGroups comes in a binary and a source version: the binary version |
| 17 |
is <b>JGroups-2.x.x.bin.zip</b>, the source version is <b>JGroups-2.x.x.src.zip</b> |
| 18 |
. The binary version contains the JGroups JAR file, plus a number of |
| 19 |
JARs needed by JGroups. The source version contains all |
| 20 |
source |
| 21 |
files, plus several JAR files needed by JGroups, e.g. ANT to build |
| 22 |
JGroups from source.<br> |
| 23 |
<br> |
| 24 |
<h3> Requirements</h3> |
| 25 |
<ul> |
| 26 |
<li>JGroups 2.2.8 has a version that runs on JDK 1.3, and one that |
| 27 |
requires 1.4 or higher.<br> |
| 28 |
</li> |
| 29 |
<li>From JGroups 2.2.9 on, the required JDK is 1.4 or higher. There |
| 30 |
is no JNI code present so it should run on all platforms.</li> |
| 31 |
<li>JGroups 2.5 requires JDK 5 or higher<br> |
| 32 |
</li> |
| 33 |
<li> An XML parser is required for configuration of JGroups if |
| 34 |
you want the ability to use XML configuration files for class mapping, |
| 35 |
and to read protocol stack specifications in XML format. Not using an |
| 36 |
XML parser will result in slower serialization and limit you to use |
| 37 |
only |
| 38 |
plain protocol stack configuration strings. Note that any other JAXP |
| 39 |
compliant XML parser can |
| 40 |
be used. This is only relevant for JDK 1.3; higher JDKs come with an |
| 41 |
XML parser.<br> |
| 42 |
</li> |
| 43 |
<li>If you want to generate HTML-based test reports from the |
| 44 |
unittests, then xalan.jar needs to be in the CLASSPATH (also available |
| 45 |
in the lib |
| 46 |
directory)<br> |
| 47 |
</li> |
| 48 |
</ul> |
| 49 |
<br> |
| 50 |
<h3> Installing the binary distribution</h3> |
| 51 |
The binary version contains<br> |
| 52 |
<ol> |
| 53 |
<li>jgroups-all.jar: the JGroups library including the demos</li> |
| 54 |
<li>jgroups.bat/jgroups.sh: convenience script to start demo programs |
| 55 |
(set the CLASSPATH etc) - see below</li> |
| 56 |
<li>Some sample configuration files, udp.xml, mping.xml etc<br> |
| 57 |
</li> |
| 58 |
<li>CREDITS: list of contributors</li> |
| 59 |
<li>INSTALL.html: this file</li> |
| 60 |
</ol> |
| 61 |
We no longer ship the Xerces JARs. To run JGroups you have to have an |
| 62 |
XML parser installed on your system. If you use JDK 1.4, you can use |
| 63 |
the parser that is shipped with it.<br> |
| 64 |
<br> |
| 65 |
<br> |
| 66 |
Place the JAR files somewhere in your <b>CLASSPATH</b>, and you're |
| 67 |
ready to start using JGroups. If you already have Xerces installed, or |
| 68 |
if you have another XML parser, the Xerces JARs can be omitted.<br> |
| 69 |
If you want to use the JGroups JMS protocol |
| 70 |
(org.jgroups.protocols.JMS), then you will also need to place jms.jar |
| 71 |
somewhere in your CLASSPATH.<br> |
| 72 |
<br> |
| 73 |
<h3>Installing the source distribution</h3> |
| 74 |
The source version consists of the following directories:<br> |
| 75 |
<ol> |
| 76 |
<li>src: the sources</li> |
| 77 |
<li>test: unit and stress tests<br> |
| 78 |
</li> |
| 79 |
<li>conf: configuration files needed by JGroups, plus default |
| 80 |
protocol stack definitions</li> |
| 81 |
<li>doc: documentation</li> |
| 82 |
<li>lib: various JARs needed to build and run JGroups:</li> |
| 83 |
<ol> |
| 84 |
<li><a href="http://jakarta.apache.org/ant">Ant</a> JARs: used to |
| 85 |
build JGroups. If you already have Ant installed, you won't need these |
| 86 |
files</li> |
| 87 |
<li>jms.jar: JMS library. Needed if you intend to run the |
| 88 |
org.jgroups.protocols.JMS protocol</li> |
| 89 |
<li>junit.jar: to run the <a href="http://www.junit.org">JUnit</a> |
| 90 |
test cases</li> |
| 91 |
<li><a href="http://xml.apache.org">xalan.jar</a> : to format the |
| 92 |
output of the JUnit tests using an XSLT converter to HTML</li> |
| 93 |
<li>log4j.jar</li> |
| 94 |
<li>etc<br> |
| 95 |
</li> |
| 96 |
</ol> |
| 97 |
</ol> |
| 98 |
<br> |
| 99 |
<h3>Building JGroups (source distribution |
| 100 |
only)</h3> |
| 101 |
<ol> |
| 102 |
<li>Unzip the source distribution, e.g. unzip JGroups-2.x.x.src.zip. |
| 103 |
This will create the JGroups-2.x.x directory (root directory) under the |
| 104 |
current directory.<br> |
| 105 |
</li> |
| 106 |
<li> cd to the root directory</li> |
| 107 |
<li>Modify build.properties if you want to use a Java compiler other |
| 108 |
than |
| 109 |
javac (e.g. jikes)<br> |
| 110 |
</li> |
| 111 |
<li> On UNIX systems use <tt>build.sh</tt>, on Windows <tt>build.bat: |
| 112 |
$> <b>./build.sh compile</b></tt></li> |
| 113 |
<li> This will compile all Java files (into the <tt>classes</tt> |
| 114 |
directory).</li> |
| 115 |
<li>To generate the JARs: <tt>$> <b>./build.sh jar</b></tt></li> |
| 116 |
<li>This will generate the following JAR files in the <tt>dist</tt> |
| 117 |
directory:<br> |
| 118 |
<ul> |
| 119 |
<li><tt>jgroups-core.jar</tt> - the core JGroups libraries</li> |
| 120 |
<li><tt>jgroups-all.jar</tt> - the complete JGroups libraries |
| 121 |
including demos and unit tests</li> |
| 122 |
</ul> |
| 123 |
</li> |
| 124 |
<li>The <b>CLASSPATH </b>now has to be set accordingly: the |
| 125 |
following directories and/or JARs have to be included:</li> |
| 126 |
<ol> |
| 127 |
<li><b><JGroups rootdir>/classes</b></li> |
| 128 |
<li><b><JGroups rootdir>/conf</b></li> |
| 129 |
<li>All needed JAR files in <b><JGroups rootdir>/lib</b>. To |
| 130 |
build from |
| 131 |
sources, the two Ant JARs are required. To run unit tests, the JUnit |
| 132 |
(and |
| 133 |
possibly Xalan) JARs are needed.<br> |
| 134 |
</li> |
| 135 |
</ol> |
| 136 |
<li>To generate JavaDocs simple run $> .<b>/<tt>build.sh |
| 137 |
javadoc</tt></b> and the Javadoc documentation will be generated in |
| 138 |
the <tt>dist/javadoc</tt> directory</li> |
| 139 |
<li>Note that - if you already have Ant installed on your system - |
| 140 |
you do not need to use build.sh or build.bat, simply invoke ant on the |
| 141 |
build.xml file. To be able to invoked ant from any directory below the |
| 142 |
root directory, place <b>ANT_ARGS="-find build.xml -emacs"</b> into |
| 143 |
the <b>.antrc</b> |
| 144 |
file in yourhome directory.<br> |
| 145 |
</li> |
| 146 |
<li> For more details on Ant see <a |
| 147 |
href="http://jakarta.apache.org/ant/"> http://jakarta.apache.org/ant/</a> |
| 148 |
.</li> |
| 149 |
</ol> |
| 150 |
<h3> Testing your Setup</h3> |
| 151 |
To see whether your system can find the JGroups classes, execute the |
| 152 |
following command: |
| 153 |
<pre><b>java org.jgroups.Version<br></b></pre> |
| 154 |
<br> |
| 155 |
or (from JGroups 2.2.8 on)<br> |
| 156 |
<b><br> |
| 157 |
java -jar jgroups-all.jar<br> |
| 158 |
<br> |
| 159 |
</b><br> |
| 160 |
You should see the following output (more or less) if the class is |
| 161 |
found: |
| 162 |
<pre><br>Version: 2.2.8 RC1<br>CVS: $Id: INSTALL.html,v 1.11 2009/12/02 13:00:10 belaban Exp $<br>History: (see doc/history.txt for details)<br><br><br></pre> |
| 163 |
<h3>Running the performance tests</h3> |
| 164 |
<pre><br></pre> |
| 165 |
By default, we're running 2 senders with 10000 1K messages each, to do |
| 166 |
this, execute the following in 2 shells:<br> |
| 167 |
<br> |
| 168 |
<pre> ./jgroups.sh tests.perf.Test -config ./config.txt -props ./udp.xml -sender</pre> |
| 169 |
<br> |
| 170 |
You should see output like the following in both shells:<br> |
| 171 |
<br> |
| 172 |
<pre>-- results:</pre> |
| 173 |
<pre><br>192.168.5.2:4301 (myself):</pre> |
| 174 |
<pre>num_msgs_expected=20000, num_msgs_received=20000 (loss rate=0.0%), received=20MB, time=3750ms, msgs/sec=5333.33, throughput=5.33MB</pre> |
| 175 |
<pre><br>192.168.5.2:4311:</pre> |
| 176 |
<pre>num_msgs_expected=20000, num_msgs_received=20000 (loss rate=0.0%), received=20MB, time=3750ms, msgs/sec=5333.33, throughput=5.33MB</pre> |
| 177 |
<pre><br>combined: 5333.33 msgs/sec averaged over all receivers (throughput=5.33MB/sec)</pre> |
| 178 |
<br> |
| 179 |
<h3> Running a Demo Program</h3> |
| 180 |
To test whether JGroups works okay on your machine, run |
| 181 |
<pre><b>./jgroups.sh demos.Draw</b></pre> |
| 182 |
twice (use jgroups.bat on Windows). 2 whiteboard windows should appear. |
| 183 |
If you started them |
| 184 |
simultaneously, they should initially show a membership of 1 in their |
| 185 |
title bars. After some time, both windows should show 2. This means |
| 186 |
that the two instances |
| 187 |
found each other and formed a group. |
| 188 |
<p>When drawing in one window, the second instance should also be |
| 189 |
updated. As the default group transport uses IP multicast, make sure |
| 190 |
that - if |
| 191 |
you want to start the 2 instances in different subnets - IP multicast |
| 192 |
is enabled. If this is not the case, the 2 instances won't 'find' each |
| 193 |
other and the sample won't work. </p> |
| 194 |
<p>You can change the properties of the demo to for example use a |
| 195 |
different transport if multicast doesn't work (it should always work on |
| 196 |
the same |
| 197 |
machine). For example, to use udp.xml, execute:</p> |
| 198 |
<pre>./jgroups.sh demos.Draw -props ./udp.xml</pre> |
| 199 |
<p> </p> |
| 200 |
<h3> Using IP Multicasting without a network connection</h3> |
| 201 |
Sometimes there isn't a network connection (e.g. DSL modem is down), or |
| 202 |
we want to multicast only on the local machine. For this the loopback |
| 203 |
interface (typically lo) can be configured, e.g. |
| 204 |
<pre><b>route add -net 224.0.0.0 netmask 224.0.0.0 dev lo</b></pre> |
| 205 |
This means that all traffic directed to the 224.0.0.0 network will |
| 206 |
be sent to the loopback interface, which means it doesn't need any |
| 207 |
network to be running. Note that the 224.0.0.0 network is a placeholder |
| 208 |
for all multicast addresses in most UNIX implementations: it will catch |
| 209 |
<b>all</b> multicast traffic. This is an undocumented feature of |
| 210 |
/sbin/route and may not work across all UNIX flavors. The above |
| 211 |
instructions may also work for Windows systems, but this hasn't been |
| 212 |
tested. Note that not all systems allow multicast traffic to use the |
| 213 |
loopback interface. |
| 214 |
<p>Typical home networks have a gateway/firewall with 2 NICs: the first |
| 215 |
(eth0) is connected to the outside world (Internet Service Provider), |
| 216 |
the second (eth1) to the internal network, with the gateway |
| 217 |
firewalling/masquerading traffic between the internal and external |
| 218 |
networks. If no route for multicast traffic is added, the default will |
| 219 |
be to use the fdefault gateway, which will typically direct the |
| 220 |
multicast traffic towards the ISP. To prevent |
| 221 |
this (e.g. ISP drops multicast traffic, or latency is too high), we |
| 222 |
recommend to add a route for multicast traffic which goes to the |
| 223 |
internal network |
| 224 |
(e.g. eth1). <br> |
| 225 |
</p> |
| 226 |
<h3> It doesn't work !</h3> |
| 227 |
Make sure your machine is set up correctly for IP multicast. There |
| 228 |
are 2 test programs that can be used to detect this: McastReceiverTest |
| 229 |
and McastSenderTest. Start McastReceiverTest, e.g. |
| 230 |
<pre><b>./jgroups.sh tests.McastReceiverTest -mcast_addr 224.10.10.10 -port 5555</b></pre> |
| 231 |
Then start McastSenderTest: |
| 232 |
<pre><b>./jgroups.sh tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555</b></pre> |
| 233 |
You should be able to type in the McastSenderTest window and see the |
| 234 |
output in the McastReceiverWindow. If not, try to use -ttl 32 in the |
| 235 |
sender. If this still fails, consult a system administrator to help you |
| 236 |
setup IP multicast correctly. If you <b>are</b> the system |
| 237 |
administrator, look |
| 238 |
for another job :-) |
| 239 |
<p>Other means of getting help: there is a public forum on <a |
| 240 |
href="http://jira.jboss.com/jira/browse/JGRP">JIRA</a> for questions. |
| 241 |
Also consider subscribing to the javagroups-users mailing list to |
| 242 |
discuss such and other problems. </p> |
| 243 |
<p><br> |
| 244 |
</p> |
| 245 |
<h3>The instances still don't find each other ! </h3> |
| 246 |
<p>In this case we have to use a sledgehammer (running only under JDK |
| 247 |
1.4. and higher): we can enable the above sender and receiver test to |
| 248 |
use all |
| 249 |
available interfaces for sending and receiving. One of them will |
| 250 |
certainly |
| 251 |
be the right one... Start the receiver as follows:</p> |
| 252 |
<pre><b>java org.jgroups.tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces</b><br></pre> |
| 253 |
<p>The multicast receiver uses the 1.4 functionality to list <i><b>all |
| 254 |
available network interfaces and bind to all of them</b></i> (including |
| 255 |
the loopback interface). This means that whichever interface a packet |
| 256 |
comes in on, we |
| 257 |
will receive it.<br> |
| 258 |
Now start the sender:<br> |
| 259 |
</p> |
| 260 |
<pre><b>./jgroups.sh tests.McastSenderTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces</b><br></pre> |
| 261 |
<h3></h3> |
| 262 |
<p>The sender will also determine the available network interfaces and |
| 263 |
send each packet over all interfaces.</p> |
| 264 |
<p>This test can be used to find out which network interface to bind to |
| 265 |
when previously no packets were received. E.g. when you see the |
| 266 |
following output in the receiver:</p> |
| 267 |
<pre>bash-2.03$ <b>./jgroups.sh tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -bind_addr 192.168.168.4</b><br>Socket=0.0.0.0/0.0.0.0:5555, bind interface=/192.168.168.4<br>dd [sender=192.168.168.4:5555]<br>dd [sender=192.168.168.1:5555]<br>dd [sender=192.168.168.2:5555]</pre> |
| 268 |
<p>you know that you can bind to any of the 192.168.168.{1,2,4} |
| 269 |
interfaces to receive your multicast packets. In this case you would |
| 270 |
need to modify |
| 271 |
your protocol spec to include bind_addr=192.168.168.2 in UDP, e.g. <b>"UDP(mcast_addr=228.8.8.8;bind_addr=192.168.168.2):..."</b> |
| 272 |
.</p> |
| 273 |
<p><br> |
| 274 |
</p> |
| 275 |
<p>Alternatively you can use McastDiscovery1_4 (runs only on JDK 1.4). |
| 276 |
Start this program simultaneously on multiple machines. Binding to all |
| 277 |
available interfaces, this program tries to discover what other members |
| 278 |
are available in a network and determines which interfaces should be |
| 279 |
used by UDP. After some time (e.g. 30 seconds), press <enter> on |
| 280 |
each program. The program will then list the interfaces which can be |
| 281 |
used to bind to. There may be |
| 282 |
one or multiple interfaces. When there are multiple interfaces listed, |
| 283 |
take |
| 284 |
the one with the highest number of responses (at the top of the list). |
| 285 |
The |
| 286 |
UDP protocol spec can then be changed to explicitly bind to that |
| 287 |
interface, |
| 288 |
e.g.<br> |
| 289 |
</p> |
| 290 |
<p><b>"UDP(bind_addr=<interface>;...)"</b><br> |
| 291 |
</p> |
| 292 |
<p><br> |
| 293 |
</p> |
| 294 |
<h3>Problems with IPv6</h3> |
| 295 |
<p>Another source of problems might be the use of IPv6, and/or |
| 296 |
misconfiguration |
| 297 |
of <b>/etc/hosts</b>. If you communicate between an IPv4 and an IPv6 |
| 298 |
host, |
| 299 |
and they are not able to find each other, try the <b>java.net.preferIP4Stack=true</b> |
| 300 |
property, e.g.<br> |
| 301 |
</p> |
| 302 |
<p><b>java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw |
| 303 |
-props |
| 304 |
file:c:\\udp.xml<br> |
| 305 |
</b></p> |
| 306 |
<p>JDK 1.4.1 uses IPv6 by default, although is has a dual stack, that |
| 307 |
is, |
| 308 |
it also supports IPv4. <a |
| 309 |
href="http://java.sun.com/j2se/1.4/docs/guide/net/ipv6_guide/">Here's </a>more |
| 310 |
details on the subject.<br> |
| 311 |
</p> |
| 312 |
<p><br> |
| 313 |
</p> |
| 314 |
<h3> I have discovered a bug !</h3> |
| 315 |
If you think that you discovered a bug, submit a bug report on <a |
| 316 |
href="http://jira.jboss.com/jira/browse/JGRP">JIRA</a> or send email |
| 317 |
to javagroups-developers if you're unsure about it. Please include the |
| 318 |
following information: |
| 319 |
<ul> |
| 320 |
<li> Version of JGroups (j<tt>ava org.jgroups.Version</tt>)</li> |
| 321 |
<li> Platform (e.g. Solaris 8)</li> |
| 322 |
<li> Version of JDK (e.g. JDK 1.4.2_07)</li> |
| 323 |
<li> Stack trace. Use kill -3 PID on UNIX systems or CTRL-BREAK on |
| 324 |
windows machines</li> |
| 325 |
<li> Small program that reproduces the bug</li> |
| 326 |
</ul> |
| 327 |
<br> |
| 328 |
<br> |
| 329 |
<br> |
| 330 |
<br> |
| 331 |
<br> |
| 332 |
<br> |
| 333 |
<br> |
| 334 |
</body> |
| 335 |
</html> |