/
installation.xml
479 lines (407 loc) · 18.7 KB
/
installation.xml
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
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
<chapter>
<title>Installation and Configuration</title>
<para>The installation refers to version 2.8 of JGroups. Refer to the installation
instructions that are shipped with JGroups for details.</para>
<para>Note that these instructions are also available in the
JGroups distribution (<filename>INSTALL.HTML</filename>).
</para>
<para>JGroups comes in a binary and a source version: the binary
version is <filename>JGroups-2.x.x.bin.zip</filename>, the source
version is <filename>JGroups-2.x.x.src.zip</filename>. 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.
</para>
<section>
<title>Requirements</title>
<itemizedlist>
<listitem>
<para>JGroups 2.5 requires JDK 1.5 or higher. Version 2.9 requires JDK 1.6 or higher.</para>
</listitem>
<listitem>
<para>There is no JNI code present so JGroups should run on all platforms.</para>
</listitem>
<listitem>
<para>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)</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Installing the binary distribution</title>
<para>The binary version contains</para>
<orderedlist>
<listitem>
<para>jgroups-all.jar: the JGroups library including the
demos</para>
</listitem>
<listitem>
<para>CREDITS: list of contributors</para>
</listitem>
<listitem>
<para>INSTALL.html: this file</para>
</listitem>
<listitem>
<para>log4j.jar. This JAR is optional, for example if JDK logging is used, we don't need it. Note that
commons-logging is not a requirement any more since version 2.8.</para>
</listitem>
</orderedlist>
<para>Place the JAR files somewhere in your <envar>CLASSPATH</envar>, and you're ready to start using JGroups.
</para>
</section>
<section>
<title>Installing the source distribution</title>
<para>The source version consists of the following directories and files:</para>
<orderedlist>
<listitem>
<para>src: the sources</para>
</listitem>
<listitem>
<para>test: unit and stress tests</para>
</listitem>
<listitem>
<para>conf: configuration files needed by JGroups, plus default protocol stack definitions</para>
</listitem>
<listitem>
<para>doc: documentation</para>
</listitem>
<listitem>
<para>lib: various JARs needed to build and run
JGroups:</para>
<orderedlist>
<listitem>
<para>
<ulink url="http://jakarta.apache.org/ant/">Ant
</ulink>
JARs: used to build JGroups. If you already have Ant installed, you won't need these files
</para>
</listitem>
<listitem>
<para>
<ulink url="http://xml.apache.org/">xalan.jar</ulink>: to format the output of
the JUnit tests using an XSLT converter to HTML
</para>
</listitem>
<listitem>
<para>log4j.jar</para>
</listitem>
<listitem>
<para>etc</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</section>
<section>
<title>Building JGroups (source distribution only)</title>
<orderedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>cd to the root directory</para>
</listitem>
<listitem>
<para>Modify build.properties if you want to use a Java
compiler other than javac (e.g. jikes), or if you want to change the
interface JGroups uses for sending and receiving messages</para>
</listitem>
<listitem>
<para>On UNIX systems use <filename>build.sh</filename>, on Windows
<filename>build.bat</filename>:
<userinput>$>
./build.sh compile</userinput>
</para>
</listitem>
<listitem>
<para>This will compile all Java files (into the <filename>classes</filename> directory).
</para>
</listitem>
<listitem>
<para>To generate the JARs:
<userinput>$> ./build.sh jar</userinput>
</para>
</listitem>
<listitem>
<para>This will generate the following JAR files in the
<filename>dist</filename> directory:
</para>
<itemizedlist>
<listitem>
<para>
<filename>jgroups-core.jar</filename>
- the core JGroups library without unit tests and demos
</para>
</listitem>
<listitem>
<para>
<filename>jgroups-all.jar</filename>
- the complete JGroups library including demos and unit tests
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>The
<filename>CLASSPATH</filename>
now has to be set accordingly: the following directories and/or JARs have to be included:
</para>
<orderedlist>
<listitem>
<para>
<filename><JGroups
rootdir>/classes</filename>
</para>
</listitem>
<listitem>
<para>
<filename><JGroups
rootdir>/conf</filename>
</para>
</listitem>
<listitem>
<para>All needed JAR files in
<filename><JGroups
rootdir>/lib</filename>
. To build from sources, the two
Ant JARs are required. To run unit tests, the JUnit (and
possibly Xalan) JARs are needed.
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>To generate JavaDocs simple run
<userinput>$>
./build.sh javadoc</userinput>
and the Javadoc documentation will
be generated in the
<filename>dist/javadoc</filename>
directory
</para>
</listitem>
<listitem>
<para>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
<userinput>ANT_ARGS="-find build.xml -emacs"</userinput>
into
the
<filename>.antrc</filename>
file in your home
directory.
</para>
</listitem>
<listitem>
<para>For more details on Ant see
<ulink url="http://jakarta.apache.org/ant/"/>.
</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Testing your Setup</title>
<para>To see whether your system can find the JGroups classes,
execute the following command:</para>
<screen>
java org.jgroups.Version
</screen>
<para>or (from JGroups 2.2.8 on)</para>
<screen>
java -jar jgroups-all.jar
</screen>
<para>You should see the following output (more or less) if the
class is found:</para>
<screen>
[mac] /Users/bela/JGroups$ java org.jgroups.Version
Version: 2.8.0.GA
CVS: $Id: installation.xml,v 1.9 2010/02/11 10:51:45 belaban Exp $
</screen>
</section>
<section>
<title>Running a Demo Program</title>
<para>To test whether JGroups works okay on your machine, run
the following command twice:</para>
<screen>
java org.jgroups.demos.Draw
</screen>
<para>2 whiteboard windows should appear as shown in <xref linkend="DrawScreenshotFig"/>.
<figure id="DrawScreenshotFig"><title>Screenshot of 2 Draw instances</title>
<graphic fileref="images/DrawScreenshot.png" format="PNG" align="center" />
</figure>
Both windows should show 2 in their title bars. This means that the two instances found each other
and formed a group.</para>
<para>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 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.</para>
<para>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). Please consult the documentation to see how to do this.</para>
<para>
State transfer (see the section in the API later) can also be tested by passing the -state flag to Draw.
</para>
</section>
<section>
<title>Using IP Multicasting without a network connection</title>
<para>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.</para>
<screen>
route add -net 224.0.0.0 netmask 240.0.0.0 dev lo
</screen>
<para>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
<emphasis>all</emphasis> multicast
traffic. This is an undocumented feature of
<filename>/sbin/route</filename>
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.
</para>
<para>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).</para>
</section>
<section id="ItDoesntWork">
<title>It doesn't work !</title>
<para>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.</para>
<screen>
java org.jgroups.tests.McastReceiverTest -mcast_addr 224.10.10.10 -port 5555
</screen>
<para>Then start McastSenderTest:</para>
<screen>
java org.jgroups.tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555
</screen>
<para>If you want to bind to a specific network interface card (NIC), use -bind_addr 192.168.0.2,
where 192.168.0.2 is the IP address of the NIC to which you want to bind. Use this parameter in both
sender and receiver.</para>
<para>You should be able to type in the McastSenderTest window and
see the output in the McastReceiverTest. 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 :-)</para>
<para>Other means of getting help: there is a public forum on
<ulink url="http://jira.jboss.com/jira/browse/JGRP">JIRA</ulink>
for questions. Also consider subscribing to the javagroups-users
mailing list to discuss such and other problems.
</para>
</section>
<section>
<title>The instances still don't find each other !</title>
<para>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:</para>
<screen>
java org.jgroups.tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces
</screen>
<para>The multicast receiver uses the 1.4 functionality to list
<emphasis>all available network interfaces and bind to all of
them</emphasis>
(including the loopback interface). This means
that whichever interface a packet comes in on, we will receive it.
Now start the sender:
</para>
<screen>
java org.jgroups.tests.McastSenderTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces
</screen>
<para>The sender will also determine the available network
interfaces and send each packet over all interfaces.</para>
<para>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:</para>
<screen>
bash-2.03$ java org.jgroups.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]
</screen>
<para>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.
<parameter>"UDP(mcast_addr=228.8.8.8;bind_addr=192.168.168.2):..."
</parameter>
.
</para>
</section>
<section>
<title>Problems with IPv6</title>
<para>Another source of problems might be the use of IPv6, and/or misconfiguration of
<filename>/etc/hosts</filename>. If you
communicate between an IPv4 and an IPv6 host, and they are not
able to find each other, try the
<parameter>java.net.preferIP4Stack=true</parameter>
property,
e.g.
</para>
<screen>
java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw -props file:/home/bela/udp.xml
</screen>
<para>JDK 1.4.1 uses IPv6 by default, although is has a dual stack, that is, it also supports IPv4.
<ulink url="http://java.sun.com/j2se/1.4/docs/guide/net/ipv6_guide/">Here's</ulink>
more details on the subject.
</para>
</section>
<section>
<title>Wiki</title>
<para>
There is a wiki which lists FAQs and their solutions at
<ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=JGroups"/>. It is frequently updated and a useful companion
to this user's guide.
</para>
</section>
<section>
<title>I have discovered a bug !</title>
<para>If you think that you discovered a bug, submit a bug report
on
<ulink
url="http://jira.jboss.com/jira/browse/JGRP">JIRA</ulink>
or send
email to javagroups-developers if you're unsure about it. Please
include the following information:
</para>
<itemizedlist>
<listitem>
<para>Version of JGroups (java org.jgroups.Version)</para>
</listitem>
<listitem>
<para>Platform (e.g. Solaris 8)</para>
</listitem>
<listitem>
<para>Version of JDK (e.g. JDK 1.4.2_07)</para>
</listitem>
<listitem>
<para>Stack trace. Use kill -3 PID on UNIX systems or
CTRL-BREAK on windows machines</para>
</listitem>
<listitem>
<para>Small program that reproduces the bug</para>
</listitem>
</itemizedlist>
</section>
</chapter>