bafacd1f2fcede63c061bcb78319b0a3507c864b
[olsrd.git] / lib / bmf / README_BMF.txt
1 BASIC MULTICAST FORWARDING PLUGIN FOR OLSRD
2 by Erik Tromp (erik_tromp@hotmail.com)
3
4 27-04-2006: Version 1.0.1 - First release.
5
6
7 1. Introduction
8 ---------------
9
10 The Basic Multicast Flooding Plugin forwards IP-multicast and
11 IP-local-broacast traffic over an OLSRD network. It uses the
12 Multi-Point Relays (MPRs) as identified by the OLSR protocol
13 to optimize the flooding of multicast and local broadcast packets
14 to all the nodes in the network. To prevent broadcast storms, a
15 history of packets is kept; only packets that have not been seen
16 in the past 3-6 seconds are forwarded.
17
18 In the IP header there is room for only two IP-addresses:
19 * the destination IP address (in our case either a multicast
20   IP-address 224.0.0.0...239.255.255.255, or a local broadcast
21   address e.g. 192.168.1.255), and
22 * the source IP address (the originator).
23
24 For optimized flooding, however, we need more information. Let's
25 assume we are the BMF process on one node. We will need to know which
26 node forwarded the IP packet to us. Since OLSR keeps track of which
27 nodes select our node as MPR (see the olsr_lookup_mprs_set function),
28 we can determine if the node that forwarded the packet, has selected us as
29 MPR. If so, we must also forward the packet, replacing the 'forwarded-by'
30 IP-address to that of us.
31
32 Because we need more information than fits in a normal IP-header, the
33 original packets are encapsulated into a new IP packet. Encapsulated
34 packets are transported in UDP, port 50505. The source address of the
35 encapsulation packet is set to the address of the forwarder instead of
36 the originator. Of course, the payload of the encapsulation packet is
37 the original IP packet.
38
39 For local reception, each received encapsulated packets is unpacked
40 and passed into a tuntap interface which is specially created for
41 this purpose.
42
43 Here is in short how the flooding works (see also the
44 BmfEncapsulatedPacketReceived(...) function; details with respect to
45 the forwarding towards non-OLSR enabled nodes are omitted):
46   
47   On all OLSR-enabled interfaces, setup reception of packets
48     on UDP port 50505.
49   Upon reception of such a packet:
50     If the received packet was sent by ourselves, drop it.
51     If the packet was recently seen, drop it.
52     Unpack the encapsulated packet and send a copy to myself via the
53       TunTap device.
54     If I am an MPR for the node that forwarded the packet to me,
55       forward the packet to all OLSR-enabled interfaces *including*
56       the one on which it was received.
57
58 As with all good things in life, it's so simple you could have
59 thought of it yourself.
60     
61
62 2. How to build and install
63 ---------------------------
64
65 Follow the instructions in the base directory README file under
66 section II. - BUILDING AND RUNNING OLSRD. To be sure to install
67 the BMF plugin, cd to the base directory and issue the follwing
68 command at the shell prompt:
69
70   make install_all
71
72 Next, turn on the possibility to create a tuntap device (see also
73 /usr/src/linux/Documentation/networking/tuntap.txt)
74
75   mkdir /dev/net # if it doesn't exist already
76   mknod /dev/net/tun c 10 200
77   
78 Set permissions, e.g.:
79   chmod 0700 /dev/net/tun
80      
81 Edit the file /etc/olsrd.conf to load the BMF plugin. For example:
82
83   LoadPlugin "olsrd_bmf.so.1.0.1"
84   {
85     # No PlParam entries required for basic operation
86   }
87
88
89 3. How to run
90 -------------
91
92 After building and installing OLSRD with the BMF plugin, run the
93 olsrd deamon by entering at the shell prompt:
94   olsrd
95
96 Look at the output; it should list the BMF plugin, e.g.:
97
98   ---------- Plugin loader ----------
99   Library: olsrd_bmf.so.1.0.1
100   OLSRD Basic Multicast Forwarding plugin 1.0.1 (Apr 29 2006 12:57:57)
101     (C) Thales Communications Huizen, Netherlands
102     Erik Tromp (erik_tromp@hotmail.com)
103   Checking plugin interface version...  4 - OK
104   Trying to fetch plugin init function... OK
105   Trying to fetch param function... OK
106   Sending parameters...
107   "NonOlsrIf"/"eth2"... OK
108   "Drop"/"00:0C:29:28:0E:CC"... OK
109   Running plugin_init function...
110   ---------- LIBRARY LOADED ----------
111
112
113 4. How to check if it works
114 ---------------------------
115
116 To check that BMF is working, enter the folliwing command on the
117 command prompt:
118   
119   ping -I eth1 224.0.0.1
120     
121 Replace eth1 with the name of any OLSR-enabled network interface.
122
123 All OLSR-BMF nodes in the MANET should respond. For example:
124
125 root@IsdbServer:~# ping -I eth1 224.0.0.1
126 PING 224.0.0.1 (224.0.0.1) from 192.168.151.50 eth1: 56(84) bytes of data.
127 64 bytes from 192.168.151.50: icmp_seq=1 ttl=64 time=0.511 ms
128 64 bytes from 192.168.151.53: icmp_seq=1 ttl=64 time=4.67 ms (DUP!)
129 64 bytes from 192.168.151.55: icmp_seq=1 ttl=63 time=10.7 ms (DUP!)
130 64 bytes from 192.168.151.50: icmp_seq=2 ttl=64 time=0.076 ms
131 64 bytes from 192.168.151.53: icmp_seq=2 ttl=64 time=1.23 ms (DUP!)
132 64 bytes from 192.168.151.55: icmp_seq=2 ttl=63 time=1.23 ms (DUP!)
133 64 bytes from 192.168.151.50: icmp_seq=3 ttl=64 time=0.059 ms
134 64 bytes from 192.168.151.53: icmp_seq=3 ttl=64 time=2.94 ms (DUP!)
135 64 bytes from 192.168.151.55: icmp_seq=3 ttl=63 time=5.62 ms (DUP!)
136 64 bytes from 192.168.151.50: icmp_seq=4 ttl=64 time=0.158 ms
137 64 bytes from 192.168.151.53: icmp_seq=4 ttl=64 time=1.14 ms (DUP!)
138 64 bytes from 192.168.151.55: icmp_seq=4 ttl=63 time=1.16 ms (DUP!)
139
140
141 5. Adding non-OLSR interfaces to the multicast flooding
142 -------------------------------------------------------
143
144 As a special feature, it is possible to have multicast and local-broadcast
145 IP packets forwarded also on non-OLSR interfaces.
146
147 If you have network interfaces on which OLSR is *not* running, but you *do*
148 want to forward multicast and local-broadcast IP packets, specify these
149 interfaces one by one as "NonOlsrIf" parameters in the BMF plugin section
150 of /etc/olsrd.conf. For example:
151
152   LoadPlugin "olsrd_bmf.so.1.0.1"
153   {
154     # Non-OLSR interfaces to participate in the multicast flooding
155     PlParam     "NonOlsrIf"  "eth2"
156     PlParam     "NonOlsrIf"  "eth3"
157   }
158
159 If an interface is listed both as NonOlsrIf for BMF, and in the
160 Interfaces { ... } section of olsrd.conf, it will be seen by BMF
161 as an OLSR-enabled interface. Duh....
162   
163
164 6. Testing in a lab environment
165 -------------------------------
166
167 Setup IP-tables to drop packets from nodes which are not
168 direct (1-hop) neigbors. For example, to drop all packets from
169 a host with MAC address 00:0C:29:28:0E:CC, enter at the shell prompt:
170
171   iptables -A INPUT -m mac --mac-source 00:0C:29:28:0E:CC -j DROP
172
173 Edit the file /etc/olsrd.conf, and specify the MAC addresses of the nodes
174 we do not want to see; even though packets from these nodes are dropped
175 by iptables, they are still received on network interfaces which are in
176 promiscuous mode. For example:
177
178   LoadPlugin "olsrd_bmf.so.1.0.1"
179   {
180     # Drop all packets received from the following MAC sources
181     PlParam     "Drop"       "00:0C:29:C6:E2:61" # RemoteClient1
182     PlParam     "Drop"       "00:0C:29:61:34:B7" # SimpleClient1
183     PlParam     "Drop"       "00:0C:29:28:0E:CC" # SimpleClient2
184   }
185
186
187
188 7. Common problems, FAQ
189 -----------------------
190
191 Question:
192 When starting OLSRD with the BMF plugin, I can see the following
193 error messages:
194
195 OLSRD Basic Multicast Forwarding plugin: open() error: No such file or directory
196 OLSRD Basic Multicast Forwarding plugin: error creating local EtherTunTap
197 OLSRD Basic Multicast Forwarding plugin: could not initialize network interfaces!
198
199 Wat to do?
200
201 Answer:
202
203 Turn on the possibility to create a tuntap device; see section 2 of this
204 file.
205