HyperCast BINARIES Readme
June 2006
1. Overview
This is the Readme file for the HyperCast ZIP archive of the HyperCast
package. The main software in this
archive are the Hypercast executables, which are stored in the file
"lib/hypercast.jar". In
addtion, the archive also contains example Java programs, scripts, an XML file
and a certificate. HyperCast
applications and utilities (e.g., RunControl) are not included in this archive,
and must be downloaded separately.
2. Extract the ZIP archive
The ZIP archive for the binaries are usually distributed in a file with the name
hypercast-BINARIES-xxx-yyyymmdd.zip
where xxx is a tag that identifies who created the archive and yyyymmdd is the date when the archive was created. Copy the file to a directory where you want
to run HyperCast, and extract ('unzip') the
archive with a utility such as WinZip (on Windows) or the unzip command (on
Unix or Cygwin).
3. The content of the archive
The contents of the archive is this file, XML configuration files, JAR
files, and command scripts.
Directories:
lib/hypercast.jar - HyperCast software
lib/bcprov-jdk14-122.jar -
Implementation of cryptographic algorithms (www.bouncycastle.org)
lib/xalan.jar - XSLT processor for XML documents
(xml.apache.org/xalan-j/)
XML files:
hypercast.xml - HyperCast configuration file. This file
needs to be customized.
Certificate:
testcert.cer - A self-signed digital certificate for
security settings
.keystore - Java Keystore file that contains private
key for public key in testcert.cer
Note:
These files are used for the security protocols of HyperCast.They
contain a self-signed certificate and a private key for the
certificate. These
files need to be replaced by locally created files. Instructions are
provided in the Chapter on Security (available from the Design Docs link at www.hypercast.org).
Scripts:
bin/conf.sh, bin/conf.bat - starts the
HyperCast configuration editor
bin/version.sh, version/gui.bat - displays the version of HyperCast
4. Configuration files
4.1 Customizing the hypercast.xml configuration file
The provided configuration file hypercast.xml is set to the default
configuration, which runs a a Delaunay Triangulation overlay topology (with
random coordinates, buddy list rendezvous, TCP socket adapter, UDP node
adapter). All configuration files can be edited using the Configuration Editor which is
started with the script conf.sh (or conf.bat), or by editing the XML files
directly. To build a configuration from
the hypercast.xml file, the following elements need *must* be changed:
/Public/OverlayID :
Enter a string for the overlay
identifier.
/Public/NodeAdapter/NodeAdptUDP/PhyAddr/INETV4AndTwoPorts :
This is the physical address of
the node adapter, which requires one IP address and two ports. Set the value to
"0.0.0.0:9800:0". This selects
UDP port 9800 for the node adapter. If an overlay socket wants to grab the
socket and it is taken (e.g., by another overlay socket), the overlay socket
selects a different port number. The
value is currently set to "0.0.0.0:0:0". The first 4 digits are the
IP address of the hosts, the other are the port numbers for the node adapter
and the socket adapter. Setting "0.0.0.0"
selects the local IP address. Setting
"0:0" selects available ports for the node and socket adapters.
/Public/Node/DTBuddyList/Buddy/UnderlayAddress/INETV4AndOnePort:
This is the address of a
node adapter of an overlay socket. In the given configuration, the address is
an IP address and a UDP port number. Any
new overlay socket contacts this address to rendezvous with an overlay
network. The value is currently set to "0.0.0.0:0".
Change the IP address to the IP address of a running overlay socket and set the
port number to "9800". E.g.,
if you are running the application on IP address "128.143.137.144",
select the value "128.143.137.144:9800".
5. Running HyperCast
5.1 Compiling and Running HelloWorld
- Edit the configuration file hypercast.xml as discussed in 4. and copy the
file into the examples directory.
- Compile one of the HelloWorld programs with the command
> javac -classpath
".;../lib/hypercast.jar;../lib/bcprov-jdk14-122.jar;../lib/xalan.jar"
HelloWorld_CallBack.java
- In Unix, replace semicolons by colons.
- If the JAR files in ../lib are added
to the CLASSPATH environment variable, then the classpath does not need to be typed.
- Open two windows with command shells (DOS, Cygwin, Unix) and type
> java -classpath
".;../lib/hypercast.jar;../lib/bcprov-jdk14-122.jar;../lib/xalan.jar"
HelloWorld_CallBack
- Observe the messages that are exchanged.
5.2 Using Scripts
The Unix scripts (*.sh) and DOS scripts (*.bat) that can help with starting the applications. If edited to your
needs, running the scripts instead of the commands may increase the convenience
of running experiments.
The
/bin directory contains scripts to run the Configuration Editor and to
run a program that diplays version information of HyperCast. The
scripts are executed as follows:
In Unix/CYGWIN:
-
Starting the Configuration Editor:
>sh bin/conf.sh
-
Diplaying version information: >sh
bin/version.sh
In Windows, open an Explorer and click on the files ./bin/conf.bat and
./bin/version.bat.