lib/p2pd/README

   1 = OLSR P2PD plugin =
   2
   3 This README file is the main documentation source for the OLSR P2PD plugin
   4
   5 Last update 01/03/2010
   6
   7 == Description ==
   8
   9 This plugin goal is the distribution of Peer to Peer Discovery messages over an
  10 OLSR Wireless Mesh Network.
  11
  12 In a wireless mesh network, the usage of wireless interfaces in ad-hoc mode and
  13 the OLSR routing protocol prevent UDP messages to be distributed all over the
  14 network.
  15
  16 We are especially interested in the distribution of UDP messages, used for host-
  17 based service discovery, over the networks that do not directly participate in
  18 the OLSR mesh cloud.
  19
  20 This task is achieved in the following way:
  21  1. the local router picks up from the local non-OLSR (HNA) network UDP messages
  22     and encapsulates them in a new type of OLSR messages,
  23  2. the OLSR infrastructure is exploited for the transport of these messages,
  24  3. remote routers decapsulate UDP messages from received OLSR messages and send
  25     them over their attached non-OLSR networks.
  26
  27 The work could have its practical and immediate application in wireless network
  28 communities that employ the OLSR protocol.
  29
  30 The plugin captures the traffic (only IPv4 if OLSR is running IPv4 and only IPv6
  31 if OLSR is running IPv6) and encapsulates this traffic in OLSR messages that are
  32 forwarded to all the other nodes in the mesh.
  33
  34 Other nodes running the plugin will decapsulate the packets and will send them
  35 to the interfaces specified in the configuration file
  36
  37 Let's get this example topology
  38
  39 pc1->eth0 ----- eth0<-r1->ath0 -------ath0<-r2->eth0 ---------eth0<-pc2
  40
  41 r1 and r2 are OLSR routers with p2pd plugin enabled. pc1 will be able to receive
  42 UDP traffic generated at pc2 and vice versa
  43
  44 The most interesting feature is that messages are forwarded also by OLSR routers
  45 without the plugin. For example:
  46
  47 pc1->eth0 ----- eth0<-r1->ath0 ---r3----ath0<-r2->eth0 ---------eth0<-pc2
  48
  49 also in this topology UDP traffic between pc1 and pc2 is possible because r3
  50 forwards UDP plugin OLSR packets even if it is not aware of the new application.
  51
  52 == Configuration ==
  53
  54 To enable the Plugin use the following syntax
  55
  56 LoadPlugin "olsrd_p2pd.so.0.1.0"
  57 {
  58 # Specify interfaces where the hosts running Peer to Peer applications are
  59 # attached
  60 PlParam     "NonOlsrIf"   "eth0"
  61 PlParam     "NonOlsrIf"   "eth1"
  62 # P2pdTtl is the time to live given to the P2PD OLSR messages
  63 PlParam     "P2pdTtl"     "5"
  64 # Specify the UDP destination address/port for P2P node discovery
  65 # Allowed: IPv4 broadcast and multicast, IPv6 multicast only
  66 #   MS Groove
  67 PlParam     "UdpDestPort" "255.255.255.255 1211"
  68 #   MDNS multicast (draft-cheshire-dnsext-multicastdns)
  69 PlParam     "UdpDestPort" "224.0.0.251 5353"
  70 }
  71
  72 Where eth0 and eth1 are the names of the interfaces where you want to capture
  73 traffic (and decapsulate incoming traffic).
  74
  75 Note that this interfaces must not talk OLSR and also the subnets on this
  76 interfaces must be announced with an appropriate HNA entry.
  77 This version of the plugin will not chech this stuff to be properly configured!
  78
  79 P2pdTtl is the time to live given to the P2PD OLSR messages. It makes no sense
  80 to announce your services to hosts that are too many hops away, because they
  81 will experience a very bad unicast connection.
  82 With this TTL setting we can tune how far we announce our services and we make
  83 the protocol scale much better
  84
  85 === References ===
  86
  87  * OLSR Optimized Link State Routing:
  88      [http://tools.ietf.org/html/rfc3626 IETF RFC 3626]
  89
  90 === Contact ===
  91  * Caspar van Zon CHW.van.Zon@mindef.nl
  92
  93 Revision history
  94 ================
  95
  96 01/03/2010 - Changes relative to olsr_mdns plug-in which was used as a base
  97  * A new plug-in called olsrd_p2pd has been created based on the olsrd_mdns
  98    plug-in.
  99  * The initial version number for this plug-in has been set to v 0.1.0
 100  * A parameter 'UdpDestPort' was added to allow for specification of a UDP IP
 101    address/port pair.
 102  * A number of obsolete functions have been removed from the source to decrease
 103    the plug-in footprint.
 104  * A mechanism has been added to check whether duplicate messages are received
 105    and to allow them to be filtered out of the message stream. This is a new
 106    mechanism and not the one provided within OLSR because the old mechanism
 107    seems to hold a single list and this should not be contaminated. At this time
 108    the list holds tuples with information conforming draft-ietf-manet-olsrv2-10.
 109    Older non-duplicate messages are forwarded to NonOlsrIf interfaces.
 110  * Some of the return values in the olsr_parser function (p2pdc) have been
 111    changed so the related messages will not be forwarded if that is not
 112    desired.
 113  * Fragmented packets not supported.
 114  * TTL for outgoing packets are not modified.
 115  * Parameter 'UdpDestPort' is checked so only IPv4 broadcast and multicast and
 116    IPv6 multicast values are allowed as the destination address.