Iceberg Release v0 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 (Redhat distribution 6.0/6.1) and to a certain extent on FreeBSD as well. The Java programs should work on all platforms easily (not tested in Windows though). 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.

• IBM's JDK 1.1.8 -- You can find it here. Although the software might work with other versions, it is not guaranteed (some of it is known not to work very well with JDK 1.1.6 for example). IMPORTANT NOTE: It is crucial that you run all software under the same version of Java. RMI and the Ninja version of it do not work across JVM versions due to skeleton/stub check failures. If you ever get an error along these lines, then it is probably because you are running different versions of Java. 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.
• Jikes -- While you're at installing the JDK, you might as well install the jikes compiler, also from IBM. You can find it here. It is much faster than javac and saves on a lot of time with compiling all the files you are going to.
• 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).
• Ninja release 1.5 -- You can find it here. This is also required for pretty much all the Iceberg components. Some files of Ninja do not compile with jikes. They only compile with javac (jikes supposedly does more compile time checks). This is not a problem since the makefile that comes with the Ninja release uses javac. Also, a portion of the Ninja release uses JNI (Java Native Interface). The Makefile for this works with Sun's JDK, but not with IBM's JDK. To make it work for the latter, you've to edit the file classpath/ninja/gribble/distribhash/Makefile and change "genunix" to "linux" (this is to get the appropriate "jni.h" file).
• 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.
• Jacl 1.2 -- You can find it here. This is required only for the preference registry. You need to download only Jacl; Tclblend that comes alongside is not required.
• Netscape's Directory SDK 3.0/3.1 -- Download here. This is required for the client to the Naming service (the call-agent). You need to download the Java SDK.
• OpenLDAP -- This is an open source LDAP server implementation. You can find it here. This is the naming service -- you are required to install it only on the machine which is going to be the naming server. The Redhat Linux distribution comes with this package -- see if you already have it installed (look for the programs slapd, ldapadd, and ldapdelete).
• Festival speech synthesis system -- This is required at the machine where you run the APC service (or more precisely, the connector managers). Installing this is pretty straightforward, but elaborate. You can find the software here. After installing, you need to specify a site-specific initialization file in the festival/lib directory. The file name is "siteinit.scm". You can copy the one provided here.
• Viavoice -- This is required for running the mediamanager service. Download the speech recognizer and speech synthesizer along with their SDKs from here. Detailed instructions on what to download and how to install can be found as aprt of the MediaManager documentation.
• 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

You should have added the location of the "ninjarmic" program to your PATH during Ninja installation. Make sure the other executables: vat, slapd, ldapadd, ldapdelete, festival, toast, untoast, tcat, sox and mpg123 are also 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, the Ninja classpath, jacl.jar and tcljava.jar from the Jacl installation.

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

For csh: setenv JAVA_HOME /usr/local/jdk118
For bash: export JAVA_HOME=/usr/local/jdk118

Getting the Iceberg release

Get the Iceberg v0 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.

Generating Javadoc

Go to the classpath/docs directory in the package and type "make". This should make all the Javadoc files. After this, you should be able to see the Javadoc documentation here.

Configuration and Running

The Naming Service

1. First read the section "Configuring and running the naming service" in the naming service documentation.
2. Find the default location of the slapd configuration files from "man slapd.conf". Copy the slapd.oc.conf file to this default location. Copy slapd.conf as well. You may want to backup the original configuration files somewhere before overwriting.
3. For slapd.conf, edit the installation specific "directory" field. This would be the directory where the naming entries would be stored. Specify a different directory for each name-space. Create the directories you specify.
4. Also edit the "suffix" and "rootdn" entries to reflect the name-spaces you want. The examples are provided for the configuration at Berkeley.

Each name-space is distinguished by the "type-<type>" field. You should definitely specify the "type=uniq" name-space and "type=ipaddr" field. You need a separate set of entries for each additional name-space you have (an additional example given is the flat name-space of 3-digit cell-phone numbers -- see the file slapd.conf as you read this).

Adding naming entries

The naming service needs to be started before naming entries can be added. Start the service with the command "slapd".

See the section "Client operations for administering" in the naming service documentation. You need to create a file for each name-space in your installation. The "type=uniq" name-space is required for all installations since it represents Iceberg unique-ids. The "type=ipaddr" name-space is required for operation with the IPPhone IAP. And the "type=gsm" name-space is required for operation with the GSM IAP -- you can possibly ignore this since you will probably not be running this IAP in your installation.

Running the iPOP

The iPOP consists of the Call-Agent-Dispatcher service, the APC service, and the Preference registry. It is run as an iSpace service (see the Ninja 1.5 for more detailed information on this). Create a configuration file, say ipop.ispace.cfg. Be sure to specify the following: (a) The naming service location for the "iceberg.ICEConfig" service, (b) The location of the file with the list of apcHosts for the APC service (see the APC service documentation for more details), (c) The directory for the user-preference files for the preference registry (see here for details).

The iPOP is run with the following command:

java -nojit ninja.ispace.Main ipop.ispace.cfg

Note on iSpace port usage

The iSpace grabs port 1099 by default. To change this, you need to edit $HOME/.ninja/config and create/uncomment the line with "iSpace.port" to give it a non-default value. See the Ninja release for information on how to get a sample Ninja configuration file. You can get one here. Using non-default ports is necessary if you want to run more than one iSpace on a machine (easier for debugging and management).

You could create multiple Ninja configuration files and pass one of them for each iSpace you run. To do this, you would use the command:

java -nojit -Dninja.cf=my.ninja.config ninja.ispace.Main ipop.ispace.cfg

where my.ispace.config is Ninja configuration file you created.

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, Voice-mail IAP, Jukebox IAP, Mediamanager IAP, Mail client IAP, and the GSM 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 Voice-mail IAP, Mediamanager IAP, and the Jukebox IAP are server-only IAPs -- they only get incoming calls. An preference profile needs to be created for each of them. Refer their individual documentation (vm-iap.html, mm-iap.html, and jukebox-iap.html).

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.

Testing

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

• Run the naming service, create a naming service entry for the voice-mail IAP, the mediamanager IAP, and the jukebox IAP. Also create an entry for each user in your system.
• Run the iPOP.
• Create a preference profile for the voice-mail IAP, the mediamanager IAP, and the jukebox IAP. Also create a preference profile for each user in your system.
• If you are going to run the mediamanager IAP, you also need to have the Transcoder and mediamanager service up and running.

Test 1

• 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 iceberg/iap/jukebox_iap/Jukebox_Iap.java and change the location of test mp3 file (search for the variable "testMP3").
• 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.
• Try passing DTMF tones -- key in some song-number and press "#". This should switch the song (in debug mode, it might just start playing the same song again).
• Be sure to hang-up the call by pressing disconnect.

Test 2

• 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).

Test 3

• Run the Voice-Mail IAP (refer here).
• Run the VAT IAP as "yourself".
• You can place a call to the voice-mail IAP and record a playback message.
• Create a preference profile for "yourself" using the preference manager that specifies voice-mail as the default end-point.
• Restart the VAT IAP, this time running as your "friend".
• Place a call to "yourself". You should be able to hear the playback message you recorded earlier (there are some timing and buffering issues here -- sometimes, you may not hear the playback message).
• Use VAT to record a message as your "friend" for "yourself".
• You can hangup and place a similar call again to record multiple messages.
• Restart VAT IAP and run as "yourself" and call the voice-mail IAP now.
• You should be able to listen to the messages your "friend" left for you (refer here for the DTMF interface for cycling through the messages).