IP connector Application
------------------------

1. Purpose

This application will create an IP tunnel over directed diffusion protocol and
redirects certain IP traffic from the Linux kernel to directed diffusion core
for diffusion routing of the IP traffic. It enables IP-based applications
to run over directed diffusion.


2. Requirements

- TUN/TAP kernel module (available in 2.2, 2.4, and 2.6 Linux kernel)
- Root access to execute 'ip_connnector'
- Environment variable "node_addr" must be set and it must be unique within
  the same subnet. To set "node_addr" under bash, this can be done with:

bash$ export node_addr=2


3. Compiling the application

This application is bundled w/ the diffusion release and will be built when
building the diffusion software release.


4. Running IP application over diffusion

To run an IP application over diffusion, simply start 'filter_core' main
process followed by the application/filters desired (currently tested w/
one-phase pull and two-phase pull). Then start 'ip_connector' application with
root access. This will create a TUN interface (typically named tunX) with an
IP address of 10.0.0.<node_addr> and subnet mask of 255.255.255.0 by default.
To specify the address, you can use the '-a <CIDR address>' flag. The IP
address of the interface will be set to be the bitwise OR'd value of the CIDR
block prefix and 'node_addr'.

The 'ip_connector' program will subscribe to all the IP packets that are
both tunneled through diffusion and have an destination IP address of the
node's TUN interface address.

Then execute the same commands at another node. After the interest messages
are received at both nodes, the two can communicated over diffusion with an
IP-based application (i.e. ssh, ping, scp) using the TUN interface addresses.


5. Note

To enable communication between nodes in two different subnet, you need
to manually add a route to the destination subnet in the routing table at
each node.  For example, if node 1 has IP address 10.0.0.1/24 and node 2
has IP address 10.0.1.1/24, following commands are needed to be executed
manually after 'ip_connector' program successfully created the TUN interfaces:

At node 1:
bash$ route add -net 10.0.1.0 netmask 255.255.255.0 dev tun0

At node 2:
bash$ route add -net 10.0.0.0 netmask 255.255.255.0 dev tun0

Default MTU for the TUN interface is currently set at 1000. This can be
overridden by the '-m MTU' flag. However, currently release of diffusion does
not support data packet of size over 1500 byte. Thus, if setting the TUN
interface MTU at 1500 bytes or close to 1500 bytes will cause diffusion to
fail.

---------------------------------
Clarence Chung
University of Southern California
