This is the ``tgwb - Tangram Whiteboard'' README file. Contents: 1. Introduction 2. Compiling and installing 2.1 Tgif version prior to 4.1.46 2.2 Tgif version 4.1.46 and newer 3. Using 3.1 Environment 3.2 Configuration 3.3 mcastproxy 4. Known bugs 5. Further information 1. Introduction This section describes a whiteboard tool built on top of TGIF: TGWB (Tangram Whiteboard). The tgwb allows simultaneous modifications in drawings by users in a group. It is a versatile multicast distributed tool. TGWB is a module of the Tangram2, developed at LAND (http://www.land.ufrj.br). Distributed whiteboards must ensure that every member in a session has the same view of the drawings. A Reliable Multicast Library and a total ordering mechanism was developed to allow reliable multicast transmission and member view consistency. 2. Compiling and installing 2.1 Tgif versions prior to 4.1.16 TGWB is basically tgif with 3 noted differences: a) Modify Target.tmpl and change TARGET_1 to tgwb as follows: TARGET_1 = tgwb-bin b) Follow the instructions in the README file for tgif. Make all the selections and modifications you need for Tgif.tmpl. Right before you build (starting from running "xmkmf"), do the following in Tgif.tmpl: i) Replace "tgif" in the PROGRAMS line by "tgwb-bin" ii) Append the following compiler option to the MOREDEFINES line: -D_TGIF_WB2 iii) Add the following line after the SYS_LIBRARIES line: EXTRA_LIBRARIES = -L./rmcast/src -lz -lpthread -lrmcast c) This version requires the rmcast library which is included with the distribution. To build the rmcast library, simple do: cd rmcast ./configure make cd .. d) Then build tgwb: xmkmf make tgwb e) To install, execute as root: make install-tgwb 2.2 Tgif version 4.1.46 or newer Since version 4.1.46, tgif will load the reliable multicast library dynamically. If you want to use the whiteboard mode you will have to execute the following steps: a) Compile and install tgif: cd tgif- xmkf make make install b) Compile and install the reliable multicast library included in the rmcast directory within the tgif code: cd rmcast ./configure make make install OBS: to install the library in the default location (/usr/local/lib) you will need root privileges. To run tgif in whiteboard mode execute: tgif -tgwb2 OBS: If tgif could not find the reliable multicast library, you can try: tgif -tgwb2 -rmcastlibdir For instance, if librmcast.so is in the /usr/local/lib directory you can execute: tgif -tgwb2 -rmcastlibdir /usr/local/lib 3. Using TGWB 3.1 Environment The TGWB tool was develop to be used in a IP Multicast network. If Multicast is not available one can use the mcastproxy program to connect the whiteboards. More information about mcastproxy can be found in section 3.3. 3.2 TGWB Configuration The reliable multicast transmission was implemented as a function library called RML (Reliable Multicast Library). When tgwb is started the user is prompted for configuration options, such as multicast address and port and whether or not the mcastproxy (see section 3.3) program should be started. Another way to customize RML options is editing the configure file tgwb.conf, located at .tgwb directory in the user's home. The following is a TGWB configuration file example: ######################################################################### #Reliable Multicast Library configuration file #Reliable Multicast Library version RM_VERSION=1.0 #Transmission mode: 0 multicast (default), 1 unicast TRANSMISSION_MODE=0 #Multicast or Unicast IP address to send data (destination IP) DEST_IP=225.1.2.3 #Multicast or Unicast port to send data (destination port) DEST_PORT=5151 #Time to live for the packets setting (1 indicates local network) TTL=1 #Inter-packet sleep timer: #Time between packet transmissions ( choose from 0 to 65535 microseconds) MICROSLEEP=10 #Log file path - NULL disable logging (default) LOG_FILE=NULL #Random Timers Distribution: 0 uniform 1 exponential TIMER_DISTRIBUTION=0 #Timer parameters # Timers values are obtained in the intervals: # (TIMER_PARAM_A*T,(TIMER_PARAM_A+TIMER_PARAM_B)*T) for NAKs # (TIMER_PARAM_C*T,(TIMER_PARAM_C+TIMER_PARAM_D)*T) for wait for retransmitions # (TIMER_PARAM_E*T,(TIMER_PARAM_C+TIMER_PARAM_F)*T) for for retransmitions # Where # TIMER_PARAM_A, TIMER_PARAM_B, TIMER_PARAM_C, TIMER_PARAM_D, TIMER_PARAM_E and # TIMER_PARAM_F are integer constants # T is the estimated one-way delay to the senders TIMER_PARAM_A=2 TIMER_PARAM_B=2 TIMER_PARAM_C=5 TIMER_PARAM_D=2 TIMER_PARAM_E=2 TIMER_PARAM_F=2 #Host related parameters and timers: # Must contain exactly the following lines: # HOSTS_IDENTIFIED=0 # DEFAULT # host1 # host2 # ... # hostN # If HOSTS_IDENTIFIED=0 then we will read only the DEFAULT # estimated delay. HOSTS_IDENTIFIED=0 DEFAULT 50 #Max number of naks that can be sent for each packet. 100 (default) MAX_NAK=100 # We will be able to retransmit the last MAX_MEMBER_CACHE_SIZE packets from each # member of the multicast group, i.e., we will store the last # MAX_MEMBER_CACHE_SIZE PACKETS from each member of the multicast group in the # cache. 4000 (default) # # WARNING: if you set MAX_MEMBER_CACHE_SIZE to low values the protocol may fail! # MAX_MEMBER_CACHE_SIZE=4000 #Enable support for new members 1 enabled (default), 0 disabled NEW_MEMBER_SUPPORT=0 #Show transmission statistics: 0 disabled (default) 1 enabled STATISTICS=0 #Time between transmission of refresh messages (seconds) REFRESH_TIMER=10 #Loss simulation: 0 disabled (default) any float number > 0 enabled # # A note about loss simulation: # When loss simulation is enabled (LOSS_PROB > 0) we always loose the first 10 # received packets, and the first received data packet - that is, # the first burst of received packets. # After that, packets are lost according to LOSS_PROB. # Example: LOSS_PROB=30 # The first 10 received packets will be lost. # Then, 30% of the packets will be lost LOSS_PROB=0 # Time to wait, in microseconds, before leaving the multicast group. LEAVE_GROUP_WAIT_TIME=500000 # Size of the buffer of the receiver host # (maximum size of a message that may be processed by the receiver host). RCV_BUFFER_SIZE=10000 ######################################################################### 3.3 mcastproxy When IP Multicast is not available the mcastproxy program can be used to connect hosts. Suppose that students from two different campi want to use TGWB. Suppose also that multicast is available in the local networks but it is not available among the campi. In that scenario, illustrated in figure below, the mcastproxy program can be used to connect each campi. There will be one instance of mcastproxy in each campus. Each mcastproxy instance can listen to local multicast traffic and send it unicast to each other campus. The packets received through unicast are sent through multicast to local users. Campus 1 Network <----Multicast----> mcastproxy1 | | | | Unicast | | | | Campus 2 Network <----Multicast----> mcastproxy2 mcastproxy program uses a configuration file, mcastproxy.conf from the .tgwb directory located at user's home. Next is presented an example of this file. ############################################ #Multicast group address GROUPADDR=225.1.2.3 #Number of hosts to send unicast packets NADDR=2 #IP Addresses list to send unicast packets ADDRLIST 192.168.1.2 10.0.0.1 # Time to live for multicast packets TTL=1 REUSEADDR=0 # Loopback: 1 enable, 0 disable LOOPBACK=1 # Unicast port to use UCASTPORT=32566 # Multicast port to use MCASTPORT=5151 ############################################ 4. Known bugs The current release of tgwb has a few known bugs. The major one being that there is no provision made for joining a whiteboard in session; the way to get around this problem is to select New from the File Menu of a tgwb to clear all whiteboards. 5. Further Information Please read the "Copyright" file in this distribution for the copyright and licensing information. Further information can be found in the RML documentation or at http://www.land.ufrj.br/tools/rmcast