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 email@example.com.
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.
This is a huge list. Installation should go smoothly for most
- 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
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"
- 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
- 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
- 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
- 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
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
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.
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
- First read the section "Configuring and running the naming
service" in the naming service documentation.
- 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
- 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
- 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
(I've always found better performance without JIT, probably because
the Java portions are not compute intensive. And the line-number
information on any exception thrown is always useful.)
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
java -nojit -Dninja.cf=my.ninja.config ninja.ispace.Main ipop.ispace.cfg
where my.ispace.config is Ninja configuration file you
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.
To test if everything in your installation works, do the
- 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.
- 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
- 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
- You should see a VAT popping up, and should start listening to
- 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.
- 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).
- 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
- 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
- Use VAT to record a message as your "friend" for "yourself".
- You can hangup and place a similar call again to record multiple
- Restart VAT IAP and run as "yourself" and call the voice-mail
- 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).
Bhaskaran Raman, firstname.lastname@example.org
Helen J. Wang, email@example.com
Z. Morley Mao, firstname.lastname@example.org
Barbara Hohlt, email@example.com
Last modified: Sat Jun 10 11:00:08 PDT 2000