Merge branch 'stable' into pud
[olsrd.git] / 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.