
OVERVIEW
--------
This is the OverPhone software system. It implements an overlay-network 
that is optimized to route VoIP calls. It is implemented in Perl. The 
architecture is explained in the paper overphone.pdf included in this 
directory.

COPYRIGHT AND LICENSE
---------------------
Author: Raj Kumar Rajendran <raj@cs.columbia.edu> (2005)

Copyright (c) 2005-2010 Raj Kumar Rajendran. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.


RUNNING OVERPHONE
-----------------
1) Verify that you have Perl Installed. The Overphone system requires the
   Time::HiRes module. So install that if it does not exist. Also make sure 
	that Net::Ping, Carp, Sys::Hostname exist.

2) Create a list of machines that will be client nodes in the file 
	$HOME/.pl/pl.list. Each machine name or ip address should be on its own 
	line. Create a second list of overlay nodes. This list should 
	be a subset of client nodes that will do overlay routing in the file 
	$HOME/.pl/ol.list. Sample pl.list and ol.list files are provides. 
	
3) Install the PEDAEMON on all client nodes and run it. That is copy the module 
	PEDAEMON.pm and the program ds.p on those machines and run ds.p. This will 
	start the PEDAEMON server so that ovelay nodes can estimate their distance 
	to client nodes.

4) Install the overlay on all server machines and run it. 
	a) First copy the machine lists $HOME/.pl/pl.list and 
	$HOME/.pl/ol.list. 

	b) Create a file of default distances in $HOME/.pl/pl.defaults (this 
	reduces the startup time of a server). It can be created by running 
	pldefault.p or by hand. A sample pl.defaults is provided 
	where the first column is the host, the second the ping round-trip-time 
	in ms, the third the network-loss rate, the fourth the jitter-buffer 
	loss rate. 

	c) Copy the modules ONet.pm, CMDS.pm, CMDC.pm, DATAS.pm, DV.pm and 
	PEDAEMON.pm. Verify that perl and Time::Hires.pm exist on those machines. 
	Then start the overlays by running t.p.

	Each overlay node will consult ol.list and try to establish connections to 
	the other overlays. Periodically each server will report on its
	connectivity. It will also estimate distances to all nodes in the
	list pl.list. 

	The overlay is now running. Overlay-node stats are logged to 
	$HOME/.pl/dv.out.

-------------------------------------------------------------------------
ROUTING over OVERPHONE
----------------------

UPSTREAM.pm is the module that can be used to send and receive calls and 
can function as an originator or receiver of calls. In addition
it collects statistics about the call sent. 

UPSTREAM has options to ignore the overlay, choose the entry-point to the overlay, use multiple paths or use error-coding. Use perldoc UPSTREAM for details. 

RUNNING UPSTREAM
----------------
1) Start UPSTREAM in server mode on the receiving machine ( running
	ts.p does this).

2) Run UPSTREAM in client mode on the sending machine (run tc.p). Both the 
	server and client will print out statistics about the call on STDOUT.


----------------------------------------------------------------------------
FILES
-----
CMDC.pm   ds.p     ol.list      pldefault.p  README   tc.p  	overphone.pdf
CMDS.pm   DV.pm    ONet.pm      pl.defaults  t.p	  UPSTREAM.pm
DATAS.pm  OCMD.pm  PEDAEMON.pm  pl.list      send.p   ts.p


--------------------------------------------------------------------------




	
