FEDAPROXY HOWTO


************
* MOTIVATION 

Generally, this mechanism allows a running instance of fedaserv to use a
UDP port of a completely different host.  The most obvious use case is when
the instance has to run on a machine which can't have its own permanently
accessible UDP port, e.g., because it is behind a NAT of an unsuitable
type.  The mechanism is not limited to this case though.



********************
* WARNING FOR A NODE

Running a node through the proxy mechanism is possible, but you should
think twice before you actually do this.  Whenever one of your points
exchange datagrams with anyone on the FEDAnet, chances are the exchange
will go through the node; in case the node is running behind a proxy, all
the traffic going from and to your point will travel TWICE between your
node instance and your proxying machine.  Good reasons are needed to prefer
this (terribly inefficient) scheme instead of just running the node on that
publicly visible machine.



************
* PRINCIPLES

The fedaserv program is capable of working both as the proxy client
(proxyuser) and as the proxy itself.  Perhaps you won't ever want a single
instance to be both the proxy and the proxyuser, although this is also
technically possible.

The proxy instance needs as many additional UDP ports as the number of
proxyusers it is going to serve; certainly it also needs the main UDP port
for itself.  Even if it is only going to work as the proxy, having no other
goals, it still needs to communicate with its users somehow, and the ports
used for proxying are not suitable for this communication.  The good news
is that a single instance can serve as many proxyusers as it has file
descriptors, so smth. like 1018 users is the (technical) limit.

All ports are to be specified explicitly, and will be bound on the
fedaserv's instance start; until each respective proxyuser establishes
its cryptographic association with the proxy instance, all traffic coming
to the port will be silently dropped.



********************************
* CONFIGURING THE PROXY (SERVER)

Each proxy user is identified by its node_id+point pair.  The respective
peer section in your serv.conf file must specify the ``proxyuser'' peer
type and have the proxyport parameter; such a section may look like this:

peer lizzie
type proxyuser
node_id 49feb618794a8e1e4439
point 155
proxyport 32277

In most cases you don't want to specify the IP address and port for this
type of peers.

The proxy subsystem is enabled if at least one peer is configured as having
the ``proxyuser'' type.



************************
* CONFIGURING THE CLIENT

To let your fedaserv instance work through a proxy, exactly one of the
peers in the configuration file must have the type ``proxy''.  IP address
and the port must be specified for the peer of this type; you may at your
option specify the node ID and the point number as well, although these are
optional.  The peer configuration section will look like this:

peer good_friend
type proxy
ip 198.51.100.173
port 65242

In case a peer with the ``proxy'' type is found in the configuration file,
the fedaserv instance will first establish a cryptographic association with
that peer; until this is done, no other communication will take place, and
once the proxy peer is associated, all datagrams to other peers will be
sent through the proxy.

Sometimes it is desirable to let some particular peers to be reached
directly, not through the proxy.  A good example of such a peer is an
instance of fedaserv residing behind the same NAT with you, e.g., right in
your local area network (or even on the same machine).  It might also be a
good idea to work directly with any peer reachable by fixed ip:port pair in
case you're going to connect to them and you know THEY won't try connecting
you on their own.  The ``direct'' peer type lets this happen; the peer of
this type must be specified by the ip:port pair, like this:

peer fellow
type persist direct
ip 192.168.18.75
port 3498

The fedaserv instance will try associating with all ``direct'' peers
without waiting for the proxy to become available, so they will work even
if the proxy is temporarily out of service.

For the peer having the ``proxy'' type, the ``direct'' type is implied, for
obvious reasons.