root/oscgroups/trunk/README

OSCgroups client and server
(c) Ross Bencina 2005 <rossb@audiomulch.com>


OSCgroups is a system for routing OSC messages between a group of 
collaborating users. It is designed to make joining and leaving a 
group simple, and to overcome the problem of connecting multiple 
users behind different NAT routers using a NAT traversal server with 
the usual "NAT hole punching" scheme (you can put that into google 
for more info). OSCgroups also implements basic group functionality 
similar to the concept of channels in internet relay chat.

To use OSCgroups, a group of collaborators (or processes) each pick a 
unique user name and password, and all agree on a shared group name 
and group password. They then each run an OSCgroups enabled client 
which connects with a server to retrieve the names, ip addresses and 
port numbers of all other group members. This information can easily 
be refreshed over time allowing dynamic group membership, this also 
supports situations where ip addresses may change. Once an 
OSCgroups client has the list of user names, addresses and port 
numbers it could do a number of things, for example it could 
implement message forwarding to named endpoints (i.e. always send 
these messages to user 'fred' no matter what his address is) or to 
multicast messages to all other members of the group.

In this initial release of OSCgroups there is only one client: 
OscGroupClient -- which implements multicast to other group members. 
Future versions may include more advanced point-to-point routing 
functionality.

This distribution contains OSCGroupServer and OSCGroupClient, both 
written in C++. It is envisiaged that OSCgroups clients could also be 
implemented in other environments such as SuperCollider or max.msp. 



COMPILING
---------

OSCgroups is implemented using oscpack, a simple C++ library for 
packing and unpacking OSC messages. In general you should try
to build OSCgroups with a similarly timestamped snapshot of 
oscpack.

To compile oscgroups, unzip the oscgroups and oscpack archives
(or check out from the svn repository) to obtain the following  
directory structure:


/oscgroups
    Makefile
    ... (other files from the oscgroups zip)
    /bin

 /oscpack
    /osc
    /ip
    ....

If you're on the Mac or some other non-Intel platform you should
check the Makefile and change the line which specifies the endianess
for oscpack otherwise it wont work..

On Unix just type 

>make

in the oscgroups directory and the OscGroupServer and OscGroupClient 
should end up in the bin directory. If you encounter any compilation 
errors please email me. For other platforms take a look at the 
makefile and work out which source files you need to build and which 
include directories need to be on your include path.

OSCgroups should compile everywhere oscpack compiles, which is at 
least Windows, Linux and MacOSX.



RUNNING
-------

* OSCGroupsServer


To run your own OSCGroupsServer simply run the OSCGroupsServer, 
use -h to get a list of possible parameters. You can specify
the port the server listens on, limit the number of connected
users and groups, set a timeout after which the server will
forget inactive users, and specify a file to which log messages
will be written. Without any parameters the server will run
on the default port 22242


* OscGroupClient

This client registers with the server and establishes contact with 
all the other members of the specified group. It then listens on a 
specified port and transfers all traffic from there to other group 
members. It also forwards all traffic from other group members to 
another specified port on the local machine. The arguments are as 
follows (you can get a summary of this info by just passing -h). Note 
that all arguments must be supplied, and given in the order listed
below.

    servername
        an internet name such as oscgroups.iua.upf.edu or an ip address 
such as 193.145.55.19

    serverport
        the udp port which the server is listening on, the server 
defaults to 22242

    localtoremoteport
        the local port used to connect with the server and to other 
group members. 

    localtxport
        this is the port which OscGroupClient listens to and forwards 
to other group members. direct your OSC traffic to this port.

    localrxport
        this is the port which OscGroupClient forwards trafic from 
other users to. you should configure your OSC application to listen 
to this port.

    username
        a unique user name used to identify you with other clients.

    password
        a password which is used to try to make sure that no one else 
pretends to be you on the server. this isn't secure but it helps.

    groupname
        a name that all group members agree on, like a user name it 
should be unique.

    grouppassword
        a password for the group. users without the correct password 
won't be admitted to the group.


All of the port numbers specified need to be different. If multiple 
users are behind the same NAT and you experience difficulties. you 
might like to try all using a different value for localtoremoteport 
for each user, although this shouldn't usually be necessary.

OSCGroups will report if you failed to register with the server
because of an incorrect password. This could be caused by another user
with the same name being connected to the server. So try to pick 
your usernames to be unique, or use your own server. Like IRC, the 
server forgets names quickly if no client is using them.


Here's an example:


./OscGroupClient oscgroups.iua.upf.edu 22242 22243 22244 22245 tim 
timspassword testgroup testpass


with the above running in one window you could run oscdump:

OscDump localhost 22245

then all messages sent by all other group members (but not you) would 
be dumped to the console.

If you're lucky there is an OSCGroupsServer running on oscgroups.iua.upf.edu 
port 22242


If you want to run OscGroupClient on the same machine as the server 
make sure that you use a real ip address or machine name (not 
localhost or 127.0.0.1) as the servername parameter of OscGroupClient 
otherwise it won't work properly. This is a kind of bug which I don't 
really want to fix right now.


If you have a software firewall installed on your machine you may need
to ensure that the OscGroupClient executable is registered with the
firewall. If you update the executable you may need to re-register it.
Also remember that the local-to-remote port (22242) must not be blocked 
by your firewall.



PLANNED EXTENSIONS
------------------

The planned extensions can be summarised as:

    - serverless operation for locally connected machines using IP broadcast

    - compute and display ping times

    - point-to-point routing in OscGroupClient



NOTES
-----

This is an initial version and it's possible that a few things will 
change, including the protocol. Right now it isn't foolproof, the 
references below suggest it probably works behind about 80-85% of 
routers on the market today -- this is a little worrying in the 
context of using it to perform live, however the alternatives involve 
providing fallback strategies such as forwarding via a server using 
TCP on port 80 -- perhaps that can be added for version 2. There is a 
nice analysis of the Skype protocol in the references section. There 
are clearly many things which could be added to OSCGroups, but for 
now the idea is to keep it simple.

I mentioned above that OSCGroups clients could be implemented with 
other OSC enabled applications. While this is true in theory, I'm not 
sure how practical it would be because the NAT traversal strategy 
requires that the same socket be used for sending and receiving data 
to the outside world. The OscGroupClient uses a fixed port number for 
this, but that isn't strictly required.

The server protocol has been designed to be pretty general, and 
OscGroupClient doesn't really take full advantage of it. For example, 
it would be easy to implement point-to-point routing (send these 
messages only to these users), or to fire events when users join or 
leave a group.

Right now OscGroupClient parses every OSC packet it sees: this isn't 
ideal but it also isn't easy to avoid. One method might be to use 
non-bundled messages for /groupclient/ping messages so that it can 
only process non-bundled packets. Another option is to take advantage 
of the fact that every message is parsed and allow the packets to 
pass routing information. In reality the routing information would be 
easier to use if it was embedded in outbound packets (eg send this 
packet to this username). It's not obvious to me how to cleanly 
provide an interface to this functionality (or if it is really 
needed) so it hasn't been done.



SOME REFERENCES
---------------

NAT and Peer-to-peer networking
Dan Kegel
http://alumnus.caltech.edu/~dank/peer-nat.html

Peer-to-Peer Communication Across Network Address Translators
Bryan Ford, Pyda Srisuresh, Dan Kegel
http://www.brynosaurus.com/pub/net/p2pnat/

RFC3489: STUN - Simple Traversal of User Datagram Protocol (UDP)
 Through Network Address Translators (NATs)
http://www.ietf.org/rfc/rfc3489.txt

An Analysis of Skype Peer-to-Peer Internet Telephony Protocol
Salman A. Baset and Henning Schulzrinne
http://arxiv.org/ftp/cs/papers/0412/0412017.pdf

Beej's Guide to Network Programming
http://www.ecst.csuchico.edu/~beej/guide/net/


Thanks to John Lazzaro for hooking me up with the right information.