Ensemble 2.00

Release Notes and Installation Instructions

Copyright ©1997 Cornell University, Ithaca, NY, USA, Hebrew University 2000, Jerusalem Israel, IBM Israel Science and Technology 2002
All rights reserved.
Maintainer: Ohad Rodeh,

Introduction

Thank you for choosing Ensemble as your message transport system. Its platform independence allows you to interconnect a wide range of computing environments.

The following instructions guide you through the process of installing Ensemble. Click on the hypertext links for the details about each step. The installation instructions are designed to be as simple as possible. However, please read them through carefully before starting and follow them carefully. Also, please read the file RELEASE_NOTES for the latest information on this release.

These installation instructions are aimed at getting Ensemble up and running on your system as quickly as possible. After successfully installing the system, you may wish to compile Ensemble for the native instruction set of your computer. The difference is only significant when Ensemble is used in high-performance settings.

Required Software

To compile Ensemble you need Version 3.07 of the Objective Caml (O'Caml) compiler. For unix systems, you also need the make version by GNU, also known as GNU-make. For windows, you'll need the Visual Studio compiler verion 6 and the nmake tool.

O'Caml is freely available via the World Wide Web at http://caml.inria.fr/ocaml/. Please ensure you have the correct version. See the instructions below on how to obtain it.

On Unix platforms, to compile the C interface, you'll need a POSIX compliant threads package. (On Solaris and HPUX you can use the native threads library). On windows you'll need the visual-C toolkit. To compile the java client, you'll need a java compiler and runtime system. For the C-sharp code you'll need a .Net environment. On windows, to build the optimized versions the server you will also need the masm (MS Compatibility Driver) and ml (MS Macro Assembler) executables installed and located in your path.

Licensing

Ensemble code has a BSD-type license. It is copyrighted by Cornell, the Hebrew universitie, and IBM research. Ensemble is freely available software, but you must agree to the terms of the license before you can install it. We ask that you read the licensing agreement before installing Ensemble. It can be found in ensemble/LICENSE.

Installation

In order to compile the system you'll need to setup some environment variables. These will help tell the build-scripts which operating system you're using and where to find the OCaml libraries.

Make sure the Ocaml binaries are in your PATH.
Set the OCAMLLIB environment variable to the directory where you installed the O'Caml libraries. O'Caml will give you the correct value for this if you type:
```
          % ocamlc -v
          The Objective Caml compiler, version 3.07
          Standard library directory: /usr/local/lib/ocaml
      
```
The second line printed out by this is the location where O'Caml installed the libraries. In sh, you set the OCAMLLIB variable like this:
```
          OCAMLLIB=/usr/local/lib/ocaml
          export OCAMLLIB
      
```
We recommend you add these to your '.tcshrc' or equivalent for your shell. If you have some other version, then obtain version 3.07 and install it. O'Caml is freely available from http://caml.inria.fr/ocaml and is easy to install (precompiled binaries are available for Windows NT). You do not need the native code compiler, although you can compile Ensemble with it.

Install Ensemble by following the step-by-step instructions. You need to get the O'Caml compiler, extract the Ensemble software, and then compile the portions you wish to use. Installation for WIN32 and Unix platforms is similar, the difference being that on windows one needs to use 'nmake -f Makefile.nt' instead of 'make'.

How to download and extract the Ensemble software

Download Ensemble from http://www.cs.cornell.edu/Info/Projects/Ensemble/ftp.html. Ensemble is no longer encrypted. Simply unzip and untar the distribution. It will put the sources in a directory called "ensemble". On Windows NT you can use the winzip program. On Unix platforms, do it this way:

    # uncompress and untar the distribution
    gunzip ensemble-2_00.tar.gz
    tar xvf ensemble.tar

Building Ensemble

Ensemble is supported on Unix (and Unix like systems), and win32 platforms. It is tested mainly on Linux and WinXP, but also on sparc-solaris, HP-UX, NT4, WIN2000.

Configure the system. If this is a win32 platform, then there is nothing to do and you can skip this stage. Otherwise, do a

    ./configure

From the Ensemble top-level directory. This will compute your system settings and write them into the mk/env.mk file. If the settings have not been computed correctly you can alter them by hand at this point by editting mk/env.mk. The PLATFORM variable is composed of a machine-type and the operating-system type. The machine-type should be one of: sparc, i386, rs6000, alpha. The os-type should be one of: solaris, aix, hpux, linux, osf1. For example, on a standard linux OS with an intel CPU PALTFORM should be i386-linux. Compile the Ensemble system and demonstration programs as follows:

    # make the Ensemble system dependencies
    # directory: ensemble
    make depend
   
    # make the system
    make all

If all went smoothly, the initial installation is now complete, and you can try out the ensemble-daemon. The client-libraries and mtalk-demo have also been compiled. To compile the additional tests you'll need to do a

make tests

as well. You can also compile for your native instruction set. instruction set. In order to clean up the object files do:

    # clean up
    # directory: ensemble
    make clean

This will leave only the binaries (in bin/PLATFORM) and libraries (in lib/PLATFORM).

The build process automatically builds the C client. To build the java client do

    # directory: ensemble
    cd client/java
   
    # make the system
    make all

To build the C-sharp code you'll need to startup a .Net development environment and build the code in client/cs/ENS.

How to run applications

There is one demo program implemented in several different languages, it is called mtalk for multi-person talk. Basically, you run several several instances of the mtalk demo and see how they merge to form a group. Each member can send messages to all the other members. The current membership is delivered to each member.

mtalk.ml: The server version of the demo. Implemented on top of the server itself.
c_mtalk.c: C-client version of the demo. The ensemble-daemon needs to run on each participating machine.
Mtalk.java: Java version of the demo. Similar to the C-client.
Mtalk.cs: C-sharp version of the demo. Similar to the C-client.

To use java Mtalk application you'll need to set the classpath to include the ensemble.jar file installed in PLATFORM/lib. Something like:

java Mtalk.java -classpath=".:PLATFORM/lib/ensemble.jar"

should work.

For the rest of the applications, you'll need to refer to the tutorial, ensemble/doc/tut.pdf, for instructions on executing the other applications and tests.

Building the native code version

Compilation for your native instruction set results in faster code, and reduction in memory use. This step compiles all of the Ensemble sources and will take a while.

    # make the Ensemble system dependencies
    # directory: ensemble
    make depend
   
    # build native code libraries
    # directory: ensemble
    make opt

Installation is complete

This concludes the instructions for building Ensemble on Unix systems.

Building Ensemble on Multiple Platforms

Multiple versions of Ensemble can co-exist within the same directory tree. All platform-dependent files now have a separate directory describing the platform for which they were compiled. For Unix platforms, you just need to ensure that the PLATFORM variables has been correctly set by the configure script. For Windows the name of the platfrom ('nt') is embedded in the Windows NT makefiles and does not need to be set. For instance, the platform-independent bytecode library for Ensemble is called 'libens.cma' ('cma' is the O'Caml suffix used for bytecode libraryies). The platform-dependent, native code library for Ensemble on i386, Linux platforms is called 'lib/i386-linux/libens.cmxa' ('cmxa' is the O'Caml suffix for native code libraries).

All the demos are install in bin/PLATFORM, this includes the ensemble server, C-client, and java-client tests and demos.

This concludes the instructions for building Ensemble on multiple platforms.

"Make Clean"

Calling 'make clean' from the top-level directory will erase all object files in the system, and leave just the libraries and executables in the lib and bin directories. Calling 'make realclean' will erase these as well. When compiling for multiple platforms make sure to call 'make clean' between builds.

SECURITY

Ensemble supports several security properties, including user message encryption, authentication, and group member authorization. Ensemble requires the user to install PGP6.5 and CryptoKit 1.2. Previous version of PGP (2.6.3, 5.0) also work, however, we have had correctness probelms with them. In order to make ensemble with cryptographic support, FIRST, you must edit mk/config.mk. You will set the CRYPTO variable to 1, its value is zero by default. This will now link in the crypto libraries when you build executables. Now perform the following steps: Unix:

    # Make the regular crypto library
    # directory: ensemble
    make 
   
    # Make the optimized crypto library
    # directory: ensemble
    make opt

NOTE: on NT, change "make" to: "nmake -f Makefile.nt" and things should compile smoothly.

Testing CRYPTO

In order to check that your system can use the various cryptographic libraries and interfaces, use the the armadillo program in the demo directory. In order to set up PGP you'll need to use (at least) the following command:

    pgp -kg

This will generate a public/private key pair for a principal of your choice. The key-pairs are stored in your home directory under the subdirectory .pgp. Armadillo requires that the principals o1,o2 are installed. To see the set of principals you currently use:

   pgp -kv
   pub   512/2F045569 1998/06/15 o2
   pub   512/A2358EED 1998/06/15 o1
   2 matching keys found.

armadillo -prog pgp To test the PGP interface. You should see something like:

   PGP works
   check_background
   got a ticket
   background PGP works

On NT, PGP only works in the foreground, in the background due to socket select issues. If something is broken, trace the PGP execution using:

    armadillo -prog pgp -trace PGP

If more information is required use the flags:

   -trace PGP1 -trace PGP2

For a wider scale test use the exchange program. This is a test that creates a set of endpoints, with principal names: o1, o2, .., and merges them securely together into one group. Each group merge requires that group-leaders properly authenticate themselves using PGP. The test is started with all members in components containing themselves, and ends when a single secure component is created. Note that it will keep running until reaching the timeout. The timeout is set by default to 20 seconds. To invoke the test do:

    armadillo -prog exchange -n 2

To use more endpoints, increase the -n command line argument, and add more principals to your PGP database. If something goes wrong, a trace of the authentication protocol is available through

 -trace EXCHANGE

. To test security with two separate processes do the following:

   #setup and run gossip
   gossip &
   #On one machine run:
    mtalk -key 11112222333344441111222233334444 -add_prop Auth -pgp o1
   #On a second machine run:
    mtalk -key 01234567012345670123456701234567 -add_prop Auth -pgp o2

The two mtalk processes should authenticate each other and merge. The three command line arguments specify:

-key 111122223333444111122223333444 : The initial security key of the system. Should be a 32 byte string.
-add_prop Auth: Add the authentication protocol. Otherwise, stacks with different keys will not be able to merge.
-pgp o1: Specify the principal name for the system.

Performance issues with PGP

The way Ensemble uses PGP is not very efficient at the moment. However, this only effects authentication, which occurs rarely. Common operations such as Diffie-Hellman exchanges, symmetric encrtyption/decryption, and MD5 hashing are performed using the OpenSSL toolkit.

Configuration and environment variables

Here is a list of environment variables that one needs to set for Ensemble to compile correctly.

# where the source distribution of Java is located. Used to compile
# the CEJava and EJava
setenv JAVA_HOME 

# where the Ensemble configuration file is located
setenv ENS_CONFIG_FILE $HOME/.ensemble

There are many configuration options for the system's runtime. They have all been moved into a configuration-file so as not to cluter the environment variable system. Below is an example that includes the default values. Note that the configuration file is optional and the system will run with the defaults correctly.

# The set of communication transports.
ENS_MODES=DEERING 

# The user-id
ENS_ID=orodeh

# The port number used by the system
ENS_PORT=6789

# The port number of the gossip service
ENS_GOSSIP_PORT=6788

# The set of gossip hosts.
ENS_GOSSIP_HOSTS=localhost

# The set of groupd hosts
ENS_GROUPD_HOSTS=localhost

#the port number of the group-daemon service
ENS_GROUPD_PORT=6790

#The port used for IP-multicast
ENS_DEERING_PORT=6793

The additional configuration below is for PGP

#The pgp password
ENS_PGP_PASS=Wild Boar

#The pgp version used (2.6,5.0,6.5)
ENS_PGP_VERSION=2.6

The format of the configuration file is:

# comment line
key = value
# empty lines are also acceptable

Last modified: Mon Apr 12 10:40:27 IDT 2004