HyperCast ZIP Readme July 2005 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 --------------------------- If you read this file, you have downloaded a ZIP archive with name hypercast-xxx-yyyymmdd.zip where xxx is a tag that identifies where the archive was created, and yyyymmdd denote the year, month, and day when the archive was created. Copy the file to a directory where you want to run HyperCast. 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 need to be replaced by locally created files. Scripts: bin/conf.sh, bin/conf.bat - starts the HyperCast configuration editor bin/version.sh, versin/gui.bat - displays the version of HyperCast 4. Configuration files ---------------------- The provided configuration files 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/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 ------------------------------------ - Extract the ZIP file and change to directory ./examples. - Compile one of the HelloWorld programs with the command > javac -classpath "../lib/lotos.jar;../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, the classpath does not need to be typed) - Edit the configuration file ./hypercast.xml as discussed in 4. and copy the file into the ./examples directory. - Open two windows with command shells (DOS, Cygwin, Unix) and type > java -classpath "../lib/lotos.jar;../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 above applications. If edited to your needs, running the scripts instead of the commands may increase the convenience of running experiments. 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 go use the