Debian Codegraph @

INSTALL.html

raw
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&nbsp; (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 $&gt; <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:&nbsp;<tt>$&gt; <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>&lt;JGroups rootdir&gt;/classes</b></li>
128 <li><b>&lt;JGroups rootdir&gt;/conf</b></li>
129 <li>All needed JAR files in <b>&lt;JGroups rootdir&gt;/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 $&gt; &nbsp;.<b>/<tt>build.sh
137 javadoc</tt></b> and the Javadoc documentation will be generated in
138 the&nbsp; <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>&nbsp; </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 &nbsp; </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.&nbsp;</p>
243 <p><br>
244 </p>
245 <h3>The instances still don't find each other !&nbsp;</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 &lt;enter&gt; 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=&lt;interface&gt;;...)"</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 &nbsp; <br>
329 &nbsp; <br>
330 <br>
331 <br>
332 <br>
333 <br>
334 </body>
335 </html>