   ggrelay - Gadu-Gadu instant messenger protocol relaying agent
   Copyright (C) 2003 Szymon Acedanski


This small application is a simple GG relaying agent. This means, that
if you are a network administrator and applying masquerade on your
server, it's likely, that your customers would like to establish
direct connections over the masquerade using GG. This program is
intended to be the solution.


NOTE: Please read "NOTE on GG6.0" below.


Prerequisites
-------------

Current version is written to compile and work cleanly on a
little-endian (Intel-endian) machine with GNU/Linux. Perhaps future
releases will be more portable.


Installation
------------

1. login as root

2. run ./install.sh

4. run /etc/init.d/ggrelay start

5. iptables -t nat -A PREROUTING -o <external interface> -p tcp \
     --dport 8074 -j REDIRECT

6. iptables -I FORWARD -o <external iface> -d 217.17.41.0/24 \
     -p tcp --dport 443 -j REJECT

See below for more information about setting up iptables rules.


Configuration
-------------

All configuration options are to be passed directly on the command
line. Minimal configuration includes your external interface, to which
incoming DCC connections will be redirected:

ggrelay -o ppp0

In this case all connections to port 8074 will be caught and managed
so, that DCC connections will come to default IP on ppp0 and port
number 1550 (yes, all to the same port) and then will be redirected to
appropriate clients according to uins sent by remote clients.

Other interesing options include setting interfaces to be listened for
incoming GG (not DCC) connections (-i option), setting ports for GG
and DCC listeners (--gg-port, --dcc-port). Another useful parameter is
-u, which forces ggrelay to setuid to the specified user. The -d switch
tells ggrelay to fork into backgroud _after_ successful
initialization. So in general, it's reasonable to run ggrelay with:

ggrelay -i <your internal interface> -o <your external interface> \
	-u nobody -d

The next step is to configure netfilter (iptables) stuff to redirect
connections from your client machines to ggrelay. It can be simply
accomplished by

iptables -t nat -A PREROUTING -p tcp --dport 8074 -j REDIRECT

Next step should be opening port 1550 on external interface for
incoming DCC connections and port 8074 on internal interface (only if
you have port filtering enabled).

Plase beware, that if ggrelay fails (or won't be launched), then
connection attempts from your clients would be redirected to /dev/null,
so make sure that ggrelay is running whenever REDIRECT rule exists in
iptables.

Attached install.sh was written to aid in configuring startup scripts.
It creates standard rc-scripts (written for RedHat/Fedora environment,
what doesn't necessarily mean, that they won't run on other
installations) in /etc/rc.d/init.d. It also creates interactively
/etc/ggrelay/ggrelay.conf, which is just a list of command-line
parameters to be passed to ggrelay, for example:

------- CUT HERE --------
-i eth0
-o ppp0
-u nobody
-m 100
-n 20
--leave-local
------- CUT HERE --------

The -d switch is added automatically.


Configuring clients for DCC
---------------------------

There is no special configuration for ggrelay is needen on clients,
just standard enabling of direct conections:

a) on ekg: run 'set dcc 1' and then 'reconnect'
b) on Kadu: check 'Enable DCC' in Kadu -> Configuration -> Network
   tab.
c) on Windows GG: check Ustawienia -> Polaczenie -> Uzywaj polaczen
   bezposrednich. No further configuration is needed, only enabling
   DCC.

For successful work with DCC both ends have to have above settings
applied.


NOTE on GG6.0
-------------

GG 6.0 (and possibly some earlier versions) introduced
a) pedantic checks regarding dcc connections source/destination IPs
b) SSL cryptography

ggrelay is now able to overshoot the first issue without addidtional
configuration.

The second problem is cryptography - GG6 uses SSL by default and
ggrelay does not support it reliably. There is a possibility to change
the behaviour of clients without need to setup anything on the
clients. Simply blocking communication to gg servers on port 443
causes GG6 to switch to non-encrypted plain communication on standard
8074 port. As it is not the best solution now, I'm working on
incorporating cryptography support into ggrelay, currently it exists
in the source but is highly experimental and is even not expected to
work.

So it's needed to run:

iptables -I FORWARD -o <external iface> -d 217.17.41.0/24 -p tcp \
	--dport 443 -j REJECT


SSL support (highly experimental)
---------------------------------

Starting with ggrelay-1.0-rc3, there is experimental support for
OpenSSL cryptography for forwarding secured connections. Currently
main goal is to make it WinGG-compatible (so it is not yet).

If you want to enable SSL, there is a small setup script called
'sslsetup' in the scripts/ directory, which will help you configuring
SSL. You can also do it manually:

a) generate server private key and certificate using

openssl req -x509 -newkey rsa:1024 -keyout <key filename> \
	-out <certificate filename> -nodes

b) add parameters to ggrelay's commandline:

	--ssl-key <key filename>
	--ssl-cert <certificate filename>

To catch incoming SSL connections, traffic addressed to GG servers'
port 443 is to be redirected to local machine, port 8075 (can be
overriden with --ssl-port). Sample command:

iptables -t nat -A PREROUTING -p tcp -d 217.17.41.0/24 --dport 443 \
	-j REDIRECT --to-ports 8075


All commandline options
-----------------------

  -i <ip/if>, --inner-ip <ip/if>  internal IP/interface
  -o <ip/if>, --outer-ip <ip/if>  external IP/interface (recommended)
  -d, --daemonize                 go to background after
                                                       initialization
  -s <ip>, --server <ip>          add GG server
  -u <user>, --user <user>        suid to specified user at startup
  -m <num>, --gg-limit <num>      max. number of chat connections
  -n <num>, --dcc-limit <num>     max. number of DCC connections
  --static-buffers                disable dynamic buffers allocation
  --gg-port                       override chat port
  --relay-local                   catch also local-network connections
  --cascade                       turn on cascading-compatibility
  --scalable                      use bigger hashtables for large
                                                              networks
  --dcc-port                      override DCC port
  --ssl-port                      override SSL server port
  --ssl-key <file>                SSL server private key
  --ssl-cert <file>               SSL server certificate
  -l, --logging                   enable connections logging
  -v, --verbose                   repeat all messages to stderr,
                                                enable debug messages
  -h, --help, --usage             show usage information
  --version                       show version information

SECURITY WARNING: Enabling --logging introduces risk of log-flooding.

NOTE: If you plan using GG client on the masquerading machine, please
consider using different port for dcc, using --dcc-port, for example:

ggrelay -o ppp0 --dcc-port 1551


Additional notes
----------------

- "dcc rsend" sent to ggrelay'ed client will fail, but it is always
  possible to use direct "dcc send". The first should work in
  cascading mode.
 
- there is a new command-line switch --scalable, which enlarges
  UIN hashtables managed by ggrelay to meet large networks
  requirements. So if you have problems in large network, you
  may try passing --scalable to ggrelay.
 

Troubleshooting
---------------

All observed bugs/problems and feature requests please direct to me
using SourceForge <http://sourceforge.net/tracker/?group_id=96768>.
Please don't hesitate to contact me privately on
accek[at]poczta{dot}gazeta<dot>pl if you have serious problems with
this software. But before doing that, please review all revealant
documentation.

Please attach following information when reporting problems running
ggrelay:
a) ggrelay version (ggrelay --version)
b) iptables version (iptables --version)
c) kernel release (uname -a)
d) 'iptables -v -n -t nat -L' output
e) 'iptables -v -n -L' output
f) /etc/ggrelay/ggrelay.conf
g) messages generated by ggrelay compiled from sources using
   './configure --enable-debug' and started from the shell with
        ggrelay -i ... -o ... -l -v   (without -d)
   after some time, when trying to connect to the GG server or when
   attempting to establish DCC connection, etc.


Credits
-------

I would like to thank all the people, who have helped me developing
ggrelay.


Especially, best regards to 

    Przemyslaw "Przemo-c" Dubiel

for spending so much time testing the application, providing to me an
account on his server, and much more. Thank you, Przemek!


Author
------

Szymon Acedanski
ul. Sloneczna 81D/1
40-136 Katowice, POLAND
phone: +48 506 202715
email: accek{at}poczta[dot]gazeta<dot>pl

