
  Communication methods for WAN in Ibis
  -------------------------------------

  Alexandre DENIS (Alexandre.Denis@irisa.fr)


* Overview
  --------

The communications methods for WAN mainly address two problems:
-- broken connectivity due to firewalls
-- performance issues.

These mechanisms are implemented in the src/ibis/connect hierarchy.
In the current Ibis, they are enabled by default. 
Although theoretically they may be used by any Ibis implementation,
only TCPIbis and NetIbis are able to use them in the current implementation.

We distinguish two categories of communication links: control and
data.  Control links are the NetIbis control links and TCPIbis links
that are set up to establish data links. They rely on the client/server
approach.  Data links are used to actually carry data. In NetIbis and TCPIbis
their construction may involve a "control link" for parameter
negociation.  Therefore we call them "brokered links".

You can choose which method you want to use for control links and
service links through the Java properties "ibis.connect.control_links"
and "ibis.connect.data_links". The following methods are implemented:

method                control  data
-----------------------------------------
PlainTCP              yes      yes
NIOTCP                yes      yes
TCPSplice             no       yes
RoutedMessages        yes      yes
ParallelStreams       no       yes
NIOParallelStreams    no       yes
PortRange             yes      yes
AnyTCP                no       yes


* Connection Establishment Methods
  --------------------------------

  -- PlainTCP: this is the plain TCP protocol, usable for both control
     and data links. It cannot cross firewalls.

  -- NIOTCP: the same as PlainTCP, but using the java.nio interface.

  -- RoutedMessages: this protocol routes messages through a "hub". It
     crosses firewalls and offers both client/server and brokered
     connections. However, its poor performance makes it a bad candidate
     for data links. You need to run a "hub" visible from every node.

  -- TCPSplice: this is plain TCP except that connection establishment 
     is based on a splicing (aka. simultaneous SYN) mechanism instead of 
     the classic client/server handshake. This method is brokered only
     (no client/server possible). 

  -- AnyTCP: this is plain TCP except that connection establishment 
     is different: first, an ordinary client-server connection is tried,
     if that fails, the roles are reversed (often, firewalls allow for
     outgoing connections). If that fails as well, TCPSplice is used.
     This method is brokered only.

   -- PortRange: this is plain TCP, but you can set a port range that was opened
      in your firewall. Use -Dibis.connect.port_range=XXX-YYY to set the range.

   -- ParallelStreams: use multiple parallel TCP streams to improve the
      performance.  This is useful for wide area links that have a long
      latency and a large bandwidth. You can use the flag
          -Dibis.connect.NumWays=X
      to set the number of parallel streams.
      
   -- NIOParallelStreams: same as ParallelStreams, but uses the java.nio
      interface. The advantage is that nio offers a select primitive, so this
      implementation is much more efficient than ParallelStreams.
   
* Example
  -------

Example with firewalls: control links with RoutedMessages and data links
with TCPSplice.

-- Step 1- build Ibis :-)

-- Step 2- configure your application to use TCPIbis.

Alternatively, configure your application to use NetIbis with one of the
TCP variants: tcp, tcp_plain, or tcp_blk, for instance by using
-Dibis.name=net.bytes.gen.tcp_blk.

-- Step 3- start the Ibis name server on a machine visible from every 
computing node, with the -controlhub flag, e.g.:

fs0:~% ibis-nameserver -controlhub

If you want a specific port number for the control hub, you can use
the "-hubport <portnum>" flag.

-- Step 4- run the application as usual, but add the following flags:
-Dibis.connect.data_links=TCPSplice 
-Dibis.connect.control_links=RoutedMessages

In addition, if you want a specific port number for the control hub,
you can use
-Dibis.connect.hub.port=<portnum>

If TCPSplice fails, you can try
-Dibis.connect.data_links=RoutedMessages instead, but this is slow.

* Reference
  ---------

Java properties:

-- ibis.connect.control_links=<method for control links>
-- ibis.connect.data_links=<method for data links>
   Chooses which method to use for control and data communications.
   Available methods are: PlainTCP, NIOTCP, TCPSplice, RoutedMessages, 
   ParallelStreams, NIOParallelStreams, PortRange, AnyTCP.
   Optional. Default is: PlainTCP for both.

-- ibis.connect.hub.host=<hostname where the hub is running>
   Not needed anymore, as the controlhub now lives within the nameserver.
-- ibis.connect.hub.port=<port the hub is listening on>
   Information on how to contact the hub control process.
   Required when RoutedMessages are used; useless else.
