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