Iceberg Release v1 Installation Notes

This document describes in sequence, the software that must be installed for getting the Iceberg release up and running. Please report installation problems and bugs to iceberg-devel@iceberg.cs.berkeley.edu.

Hardware/Software platform requirements

All software has been tested on PCs running Linux 2.2/2.4 (Redhat distribution 7.0/7.1). The Java programs should work on all platforms easily. And most of the other required software should compile easily on any Unix platform.

Pre-Installation

This is a huge list. Installation should go smoothly for most parts.

• IBMJava2-13 -- You can find it here. Although the software might work with other versions, it is not guaranteed. IMPORTANT NOTE: In general, it is good to have the same version of Java for all the components of ICEBERG running on the different machines, although technically, it should all work even with different versions. This is pretty much required for all the Iceberg components. So you've to install it in all machines on which you plan to run any Iceberg component.
• Ninja vSpace -- Note that this is not officially release, and hence is unsupported. Get it from here, unpack it, and follow instructions therein. You may have to get a libNBIO.so for your environment. See here.
• Swing 1.1.1 -- You can find it here. This is required for the GUI based programs -- the IPPhone IAP, the VAT IAP (see here), and the preference manager (see here).
• Netscape's Directory SDK 3.0/3.1 -- Download here. The library is used for some of the LDAP Distinguished Name (DN) parsing. You need to download the Java SDK.
• VAT -- You can get this as part of the MASH release here. You can just install the whole package. Your mileage with getting this to work with Linux may vary. Sometimes the older versions work better with the sound-card and driver. Sometimes bad things can happen -- the vat on my laptop causes it to hang at times because of a development version sound driver. Note: After installing, you need to make the changes to vat listed here.
• Toast GSM codec package -- This is required for the APC, for some of the IAPs (vat-iap, gsm-iap), and also for the "vatrec" utility (see here). You can find the codec here. Download and install the C-version with the libraries and header files. Before doing a "make install", you need to edit the Makefile: (a) change INSTALL_ROOT to /usr/local/ (b) change GSM_INSTALL_INC to be $(GSM_INSTALL_ROOT)/include.
• SOX package -- This should come with the Linux distribution by default. If not, you can get it here. This is required at the APC service (the ConnectorManager component).
• MPEG decoder mpg123 -- This is also installed by default with the Redhat Linux distribution. If you don't have the program "mpg123", you can download it from here.
• CPP -- The C pre-processor is required for pre-processing some of the ".jc" files both in the Ninja release as well as in the Iceberg release. Linux comes with the default installation in "/lib/cpp". Make a soft-link to this from "/usr/bin" as well. That is, issue the command "ln -s /lib/cpp /usr/bin/cpp" as root. If you don't have it installed, you can get the RPM from here. If you have a system other than RedHat, get the egcs source from the same location and install that -- cpp is part of egcs.

Iceberg Release Installation

Setting up the Environment

Make sure that the executables vat,, toast, untoast, tcat, sox and mpg123 are in your PATH.

Add the following to your CLASSPATH: ".", the JDK installation's classes.zip, ldapjdk.jar from Netscape's Directory SDK, swing.jar from the Swing installation, Ninja's CLASSPATH.

Add the "ninja2-classpath/ninja2/lib" directory to your LD_LIBRARY_PATH environment variable. You may have to get a libNBIO.so for your environment. See here.

You should set the JAVA_HOME environment variable to the location of the Java distribution. For example:

For csh: setenv JAVA_HOME /opt/IBMJava2-13
For bash: export JAVA_HOME=/opt/IBMJava2-13

Getting the Iceberg release

Get the Iceberg v1 release from here. Unpack and add the top-level "classpath" directory to your CLASSPATH environment variable.

Compiling the components

A top-level make from within the classpath/iceberg directory should compile all the components. Go to this directory and type "make" to compile everything.

After compiling, copy the "vatrec" and "vatplay" binaries from the classpath/iceberg/vat-utils directory to a location on your PATH.

Configuration and Running

The Distributed Hashtable

Distributed Hashtables are central to vSpace, on top of which ICEBERG v1 runs. Configuration for this is explained here. Run the Hashtable "bricks" in one or two (or how many ever you want) machines as described in the same document.

The Naming Service

Run the naming service as explained its documentation here. Add the naming entries as explained in the same document.

The Preference Registry

Run the Preference Registry service and add entries as explained in its documentation. While in operation (after testing), you can use the Preference Manager GUI to add entries to the registry.

Running the iPOP

The iPOP consists of the Call-Agent Service, the APC service, the Name-Mapping-Service, and the Preference Registry Service. It is run as a vSpace service (see the Ninja web-page for more detailed information on this). Create a configuration file, say ipop.cfg.demo1. Be sure to specify/change the following according to your testbed:

• The "hashtableNode" specifications -- the node:port where the hashtable bricks are running.
• The state-machine specification file for the Call Agent Service.
• Mapfile for different hosts. An example is localmap.demo1. Modify it to reflect the hostname of the iPOP in the first line, and the hashtableNode host:port values in the subsequent lines.
• The nodeFile specification under "APC_PPC_Worker". An example is apcHostnames.demo1. This file gives the list of nodes on which the APC service is running (to be precise, where the Connector Managers Workers are running).

The iPOP is run with the following command:

java ninja2.core.vspace.vSpace ipop.cfg.demo1

Running the IAPs

See the separate documentation on each of the IAPs for information on running each of them. Specifically, see the ones for IPPhone, VAT IAP, and the Jukebox IAP.

You need not run all the IAPs to begin with. See the section "Testing" below for testing if all works well.

Specifying call receiving preferences

The Jukebox IAP is a server-only IAP -- it only gets incoming calls. A preference profile needs to be created for the Jukebox IAP. Refer the documentation.

For each user in your system, you need to create a call-receiving preference and upload it to the preference registry. See the preference manager documentation for details on how to go about doing this.

General notes about running Ninja2

ICEBERG-v1 depends heavily in Ninja's vSpace. Since there has not yet been an official release of Ninja2, vSpace has its fair share of bugs. The hashtable bricks seem stable most of the times (so far as we have tested), but fails sometimes. Restart your iPOP if anything fails during its startup.

In general, you should have the distributed hashtable bricks setup and running all the time. The parameters specified in the vSpace config files are stored in the hashtable under the given "stateTableName". The parameter values are persistent across runs of the vSpace. So be careful when trying to rerun a vSpace program like the iPOP -- if you want to change some parameter in the configuration after the first run, you might have to restart the bricks. This effectively amounts to restarting the entire system usually. When restarting the hashtable bricks, its usually good to remove all the "table_*" directories where the different named hashtables were stored. Be careful not to remove the "table_template" directory, which is a configuration directory for the hashtable bricks.

Testing

To test if everything in your installation works, do the following:

• Run the distributed hashtable bricks
• Run the iPOP.
• Create a naming service entry for the jukebox IAP. Also create an entry for each user in your system.
• Create a preference profile for the jukebox IAP. Also create a preference profile for each user in your system.

Test 1

• Run two VAT IAPs on two different machines, as two different (ICEBERG) users. Let both of them use GSM voice codec. (See here).
• Make sure that the call preferences of the two users match up with the hosts on which you are running the VAT IAPs.
• Establish a call from one VAT IAP to another.

Test 2

• Continue on the previous one. Change the data format used by one of the VAT IAPs from "gsm" to "pcm-ul-8000". (Refer here).
• Establish a call from one VAT IAP to another. It should all work, except that the APC service will now instantiate a codec transformation agent for each direction of communication (toast and untoast).

Test 3

• Run the Jukebox IAP in the debug mode (refer here). For this, you need to create an mp3 file at the APC service and specify the location of this file at the Jukebox IAP. This is a hack to test the service. You may need to edit iceberg1/iap/ui/jukebox_iap/Jukebox_Iap.java and change the location of test mp3 file (search for the variable "testMP3"). Bu default, it is "/tmp/test.mp3".
• Run the VAT IAP with the "pcm-ul-8000" format (refer here). You can run as any user.
• Place a call from the VAT IAP to the Jukebox IAP by typing the Iceberg Uniq-id in email-id format (e.g. jukebox@cs.berkeley.edu).
• You should see a VAT popping up, and should start listening to the song.
• Be sure to hang-up the call by pressing disconnect.

Test 4

• Continue on the previous one. Restart the VAT IAP and run it with the "gsm" format argument.
• Placing a call to the jukebox IAP should now show similar behaviour (only that the APC service would have created a different data path).