nodescore/oscgroups/README

269 lines
9.5 KiB
Plaintext
Executable File

OSCgroups client and server
(c) Ross Bencina 2005-2013 <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
....
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.
There is a batch file for building with MinGW on Windows (make.MinGW32.bat)
There is a CMakeLists.txt file that you can use with CMake.
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.