co2
/documentation/satellite_setup
co2-home
how to set up a co2 satellite


prerequisites

plattforms:
the co2 implementation in python is developed and tested under linux. the code should run without problems on any other *nix like system for which the required python version is available. for the sorry rest, it should run with some minor modifications (i definitely don't care...).
network:
you'll need a 'real' IP address (i.e. one that is accessible from the internet) for the machine you want to run the satellite on (or appropriate forwarding on the firewall in case the machine is in a LAN).
software:
# python >= version 2.3. no additional libraries are needed.
# bzip2: to unpack the co2 archive. if you don't have it, install your linux distribution's package or get it from here.


installation

download the archive from the download page to some place in your filesystem
unpack it with tar xvjf <filename>
that's it, the software runs out of anywhere, no files must be installed in system directories.


configuration

open config.py in the toplevel co2 directory with your favourite editor. this configuration file is a python module. don't be afraid if you don't know a thing about python, it's easier to read and edit than many a config file that comes with it's own proprietary format. and, it is heavily commented. read and follow the information provided there. basically, all you have to change is the server address and the co2 home directory. for the other variables, the supplied default values should be OK.


testing

while testing, it is recommended that you set background to False, so you can follow debug- and log-statements on the console. thus, you can also stop the server by typing control c . if you set background to True, you can do a tail -f logs/log to follow the messages in realtime. then you'll have to stop the server by sending it a SIGKILL or SIGTERM (e.g. kill `cat pid`).

cd to your co2 home directory and type python2.3 co2.py. you'll see a lot of debugging messages, if there are none marked ERROR or WARNING and the last line says
<timestamp> Co2Server [<your.domain:port>]:listening... ,
you're fine.
subsequently, there will be regular apache style entries like:
<relay.name> - - [<timestamp>] "POST /RPC2 HTTP/1.0" 200 -
those are ping requests by the relay, that is looking if you're still there, and more co2 stuff like: <timestamp> Co2SatelliteRegistry: notify [{'host_id': '1.2.3.4:2003', 'data': 'nih!', 'client_address': ('1.2.3.4', 39878)}]
that's a message from satellite 1.2.3.4:2003 containing 'nih!' relayed to your satellite.


plugins

todo...


some remarks on network setup

in order to connect your co2 satellite to a co2 network whose relay is somewhere on the internet, your host must have a 'real' IP address. a 'private' address such as 192.168.0.42 won't do, unless there is appropriate forwarding done on the firewall / router you are behind. in which case incoming traffic to whatever tcp port you choose for your satellite to listen on (default 2003) must be forwarded to the IP address of your host. (don't change the host-part of the variable host in config.py to the hostname or IP of the firewall! the relay only uses the port given there and the host-part of the client address of the satellite's initial register-request for subsequent communication, which will be the firewall's anyway.)
in the unlikely case of two or more satellites behind one firewall, they will have to use different ports.

Last modified: Thu Oct 16 20:33:02 CEST 2003 - elektro/lu