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.