Update version after release of v0.6.6.1
[olsrd.git] / lib / bmf / README_BMF
1 BASIC MULTICAST FORWARDING PLUGIN FOR OLSRD
2 by Erik Tromp (eriktromp@users.sourceforge.net, erik_tromp@hotmail.com)
3 Version 1.7.0
4
5 1. Introduction
6 ---------------
7
8 The Basic Multicast Forwarding Plugin floods IP-multicast and
9 IP-local-broadcast traffic over an OLSRD network. It uses the
10 Multi-Point Relays (MPRs) as identified by the OLSR protocol
11 to optimize the flooding of multicast and local broadcast packets
12 to all the hosts in the network. To prevent broadcast storms, a
13 history of packets is kept; only packets that have not been seen
14 in the past 3-6 seconds are forwarded.
15
16
17 2. How to build and install
18 ---------------------------
19
20 Download the olsr-bmf-v1.7.0.tar.gz file and save it into your OLSRD
21 base install directory.
22
23 Change directory (cd) to your OLSRD base install directory.
24
25 At the command prompt, type:
26
27   tar -zxvf ./olsr-bmf-v1.7.0.tar.gz
28
29 then type:
30
31   make build_all
32
33 followed by:
34
35   make install_all
36
37 Next, turn on the possibility to create a tuntap interface (see also
38 /usr/src/linux/Documentation/networking/tuntap.txt):
39
40   mkdir /dev/net # if it doesn't exist already
41   mknod /dev/net/tun c 10 200
42   
43 Set permissions, e.g.:
44
45   chmod 0700 /dev/net/tun
46
47 To configure BMF in OLSR, you must edit the file /etc/olsrd.conf
48 to load the BMF plugin. For example, add the following lines:
49
50   LoadPlugin "olsrd_bmf.so.1.7.0"
51   {
52     # No PlParam entries required for basic operation
53   }
54
55
56 3. How to run
57 -------------
58
59 After building and installing OLSRD with the BMF plugin, run the
60 olsrd daemon by entering at the shell prompt:
61
62   olsrd
63
64 Look at the output; it should list the BMF plugin, e.g.:
65
66   ---------- LOADING LIBRARY olsrd_bmf.so.1.7.0 ----------
67   OLSRD Basic Multicast Forwarding (BMF) plugin 1.7.0 (Mar 22 2010 21:44:23)
68     (C) Thales Communications Huizen, Netherlands
69     Erik Tromp (eriktromp@users.sourceforge.net)
70   Checking plugin interface version:  5 - OK
71   Trying to fetch plugin init function: OK
72   Trying to fetch parameter table and it's size...
73   Sending parameters...
74   "NonOlsrIf"/"eth4"... NonOlsrIf: OK
75   Running plugin_init function...
76   OLSRD Basic Multicast Forwarding (BMF) plugin: opened 5 sockets
77   ---------- LIBRARY olsrd_bmf.so.1.7.0 LOADED ----------
78
79
80 4. How to check if it works
81 ---------------------------
82
83 Enter the following command on the command prompt:
84   
85   ping 224.0.0.1
86
87 All OLSR-BMF hosts in the OLSR network should respond. For example,
88 assume we have three hosts, with IP addresses 192.168.151.50,
89 192.168.151.53 and 192.168.151.55. On host 192.168.151.50 we enter
90 the following ping command:
91
92 root@IsdbServer:~# ping 224.0.0.1
93 PING 224.0.0.1 (224.0.0.1) 56(84) bytes of data.
94 64 bytes from 192.168.151.50: icmp_seq=1 ttl=64 time=0.511 ms
95 64 bytes from 192.168.151.53: icmp_seq=1 ttl=64 time=4.67 ms (DUP!)
96 64 bytes from 192.168.151.55: icmp_seq=1 ttl=63 time=10.7 ms (DUP!)
97 64 bytes from 192.168.151.50: icmp_seq=2 ttl=64 time=0.076 ms
98 64 bytes from 192.168.151.53: icmp_seq=2 ttl=64 time=1.23 ms (DUP!)
99 64 bytes from 192.168.151.55: icmp_seq=2 ttl=63 time=1.23 ms (DUP!)
100 64 bytes from 192.168.151.50: icmp_seq=3 ttl=64 time=0.059 ms
101 64 bytes from 192.168.151.53: icmp_seq=3 ttl=64 time=2.94 ms (DUP!)
102 64 bytes from 192.168.151.55: icmp_seq=3 ttl=63 time=5.62 ms (DUP!)
103 64 bytes from 192.168.151.50: icmp_seq=4 ttl=64 time=0.158 ms
104 64 bytes from 192.168.151.53: icmp_seq=4 ttl=64 time=1.14 ms (DUP!)
105 64 bytes from 192.168.151.55: icmp_seq=4 ttl=63 time=1.16 ms (DUP!)
106
107 We can see the response from the originating host (192.168.151.50)
108 (it is normal behaviour for hosts sending multicast packets to
109 receive their own packets). We can also see the responses by the
110 other hosts (correctly seen as DUPlicates by ping).
111
112 Note: when using an older version of ping than the standard from
113 iputils-20020927, as found in most current Linux distributions, you may want
114 to test BMF by specifying the output interface to the ping command:
115
116   ping -I bmf0 224.0.0.1
117
118 Older versions of 'ping' (e.g. as found in iputils-20020124) may bind to the
119 autoselected source address, which may be incorrect. Since BMF re-uses
120 one of the existing IP addresses for the "bmf0" network interface, the
121 older-version ping command may 'autobind' to the wrong interface.
122
123 See also the note in the iputils-20020927/RELNOTES file:
124 "* Mads Martin Jørgensen <mmj@suse.de>: ping should not bind to autoselected
125   source address, it used to work when routing changes. Return classic
126   behaviour, option -B is added to enforce binding."
127
128
129 5. How does it work
130 -------------------
131
132 In the IP header there is room for only two IP-addresses:
133 * the destination IP address (in our case either a multicast
134   IP-address 224.0.0.0...239.255.255.255, or a local broadcast
135   address e.g. 192.168.1.255), and
136 * the source IP address (the originator).
137
138 For optimized flooding, however, we need more information. Let's
139 assume we are the BMF process on one host. We will need to know which
140 host forwarded the IP packet to us. Since OLSR keeps track of which
141 hosts select our host as MPR (see the olsr_lookup_mprs_set(...) function),
142 we can determine if the host that forwarded the packet, has selected us as
143 MPR. If so, we must also forward the packet, changing the 'forwarded-by'
144 IP-address to that of us. If not, we do not forward the packet.
145
146 Because we need more information than fits in a normal IP-header, the
147 original packets are encapsulated into a new IP packet. Encapsulated
148 packets are transported in UDP, port 50698. The source address of the
149 encapsulation packet is set to the address of the forwarder instead of
150 the originator. Of course, the payload of the encapsulation packet is
151 the original IP packet. For an exact specification of the encapsulation
152 format, refer to paragraph 10 below.
153
154 For local reception, each received encapsulated packets is unpacked
155 and passed into a tuntap interface which is specially created for
156 this purpose.
157
158 There are other flooding solutions available that do not use
159 encapsulation. The problem with these solutions is that they cannot
160 prevent duplicates of forwarded packets to enter the IP stack. For
161 example, if a host is receiving flooded (unencapsulated, native IP)
162 packets via two MPR hosts, there is no way to stop the reception of
163 the packets coming in via the second MPR host. To prevent this, BMF
164 uses a combination of encapsulated flooding and local reception via
165 a tuntap interface.
166
167 Here is in short how the flooding works (see also the
168 BmfEncapsulatedPacketReceived(...) function; details with respect to
169 the forwarding towards non-OLSR enabled hosts are omitted):
170   
171   On all OLSR-enabled interfaces, setup reception of packets
172     on UDP port 50698.
173   Upon reception of such a packet:
174     If the received packet was sent by myself, drop it.
175     If the packet was recently seen, drop it.
176     Unpack the encapsulated packet and send a copy to myself via the
177       TunTap interface.
178     If I am an MPR for the host that forwarded the packet to me,
179       forward the packet to all OLSR-enabled interfaces *including*
180       the interface on which it was received.
181
182
183 6. Advanced configuration
184 -------------------------
185
186 All configuration of BMF is done via the "LoadPlugin" section in
187 the /etc/olsrd.conf file.
188
189 The following gives an overview of all plugin parameters that can be
190 configured. Unless otherwise stated, settings may differ for each node in the
191 network.
192
193   LoadPlugin "olsrd_bmf.so.1.7.0"
194   {
195     # Specify the name of the BMF network interface.
196     # Defaults to "bmf0".
197     PlParam "BmfInterface" "bmf0"
198
199     # Specify the IP address and mask for the BMF network interface.
200     # By default, the IP address of the first OLSR interface is copied.
201     # The default prefix length is 32.
202     PlParam "BmfInterfaceIp" "10.10.10.234/24"
203
204     # Enable or disable marking the BMF network interface as persistent.
205     # When the interface is persistent (default) then it will not be removed
206     # when olsrd shuts down. This is to facilitate other programs (for example
207     # multicast routing daemon mrouted) to continue using it.
208     PlParam "BmfInterfacePersistent" "yes"
209
210     # Enable or disable the flooding of local broadcast packets
211     # (e.g. packets with IP destination 192.168.1.255). Either "yes"
212     # or "no". Defaults to "yes".
213     # Note: all nodes in the same network should have the same setting for
214     # this plugin parameter.
215     PlParam "DoLocalBroadcast" "yes"
216
217     # Enable or disable the capturing packets on the OLSR-enabled
218     # interfaces (in promiscuous mode). Either "yes" or "no". Defaults
219     # to "no".
220     # The multicast (and, if configured, local broadcast) packets sent on
221     # the non-OLSR network interfaces and on the BMF network interface will
222     # always be flooded over the OLSR network.
223     # If this parameter is "yes", also the packets sent on the OLSR-enabled
224     # network interfaces will be flooded over the OLSR network.
225     # NOTE: This parameter should be set consistently on all hosts throughout
226     # the network. If not, hosts may receive multicast packets in duplicate.
227     PlParam "CapturePacketsOnOlsrInterfaces" "no"
228
229     # The forwarding mechanism to use. Either "Broadcast" or
230     # "UnicastPromiscuous". Defaults to "Broadcast".
231     # In the "UnicastPromiscuous" mode, packets are forwarded (unicast) to the
232     # best candidate neighbor; other neighbors listen promiscuously. IP-local
233     # broadcast is not used. This saves air time on 802.11 WLAN networks,
234     # on which unicast packets are usually sent at a much higher bit rate
235     # than broadcast packets (which are sent at a basic bit rate).
236     # Note: all nodes in the same network should have the same setting for
237     # this plugin parameter.
238     PlParam "BmfMechanism" "Broadcast"
239
240     # The number of times BMF will transmit the same packet whenever it decides
241     # to use broadcast to forward a packet. Defaults to 1. Not used if
242     # "BmfMechanism" is set to "UnicastPromiscuous".
243     PlParam "BroadcastRetransmitCount" "1"
244
245     # If the number of neighbors to forward to is less than or equal to the
246     # FanOutLimit, then packets to be relayed will be sent via unicast.
247     # If the number is greater than the FanOutLimit the packet goes out
248     # as broadcast. Legal values are 0...10. See MAX_UNICAST_NEIGHBORS
249     # as defined in NetworkInterfaces.h . 0 means broadcast is always used,
250     # even if there is only 1 neighbor to forward to. Defaults to 2. 
251     # This plugin parameter is not used if "BmfMechanism" is set to
252     # "UnicastPromiscuous".
253     PlParam "FanOutLimit" "2"
254
255     # List of non-OLSR interfaces to include
256     PlParam     "NonOlsrIf"  "eth2"
257     PlParam     "NonOlsrIf"  "eth3"
258   }
259
260 BmfInterfaceIp
261 --------------
262
263 By default, the BMF network interface will get the IP address of the
264 first OLSR interface, with a prefix length of 32. Having two network
265 interfaces with the same IP address may seem strange, but it is not
266 a problem, since the BMF network interface is not used in any point-to-
267 point routing.
268
269 The advantage of assigning a known OLSR IP address to the BMF network
270 interface is that multicast packets, sent via the BMF network interface,
271 get a known IP source address, to which the receivers of the packets
272 can reply. That is useful when using, for example, the command
273 "ping 224.0.0.1".
274
275 An advantage of using a prefix length of 32 is that the Linux IP
276 stack will not automatically enter a subnet routing entry (via the BMF
277 network interface) into the kernel routing table. Such a routing entry
278 would be useless, because the BMF network interface does not forward
279 point-to-point traffic.
280
281 If you configure a specific IP address and mask via the "BmfInterfaceIp"
282 parameter, BMF will cause the specified IP host address to be advertised
283 into the OLSR network via the HNA mechanism, so that the other hosts in
284 the network know how to route back.
285
286 CapturePacketsOnOlsrInterfaces
287 ------------------------------
288
289 If "CapturePacketsOnOlsrInterfaces" is set to "yes", any multicast
290 or local broadcast IP packet, sent by an application on *any* OLSR
291 interface, will be flooded over the OLSR network. Each OLSR host
292 will receive the packet on its BMF network interface, "bmf0". The
293 OLSR-interfaces will be in promiscuous mode to capture the multicast
294 or local broadcast packets.
295
296 For example, if "eth1" is an OLSR interface, the following command
297 will result in one response from each OLSR host in the network:
298
299   ping -I eth1 224.0.0.1
300
301 A disadvantage of this configuration is that a host may, in rare
302 cases, receive a multicast packet twice. This is best explained
303 by looking at the following network diagram:
304
305         eth0   eth0
306       A ----------- B
307  eth1 |            / eth1
308       |           /
309  eth0 |          /
310       C --------+
311         eth1
312
313 Suppose host A is running a ping session that is sending ping
314 packets on "eth1". The BMF process on host A will see the outgoing
315 packets on "eth1", encapsulates these packets and sends the
316 encapsulated packets on "eth0". Let's assume we are using the link
317 quality extensions of OLSR, and the 2-hop path A - B - C is better
318 (in terms of ETX) than the 1-hop path A - C. In that case host B is
319 an MPR for host A. Host B receives the encapsulated packets of host A
320 on its "eth0" interface, and, since it is an MPR, it decides to
321 forward them on "eth1".
322
323 In most cases, host C will receive the original, unencapsulated
324 ping packet on its "eth0" interface before the encapsulated
325 ping packet from host B arrives on its "eth1" interface. When the
326 encapsulated packet from B arrives, the BMF process will then see
327 that it is a duplicate and discard it.
328
329 However, in the IP world, there are no guarantees, so it may
330 happen that host C receives the encapsulated packet from host B
331 first. That packet is then unpacked and locally delivered to the
332 BMF network interface "bmf0". When the original, unencapsulated
333 packet then comes in on "eth0", there is no way to stop it from
334 being received (for a second time) by the Linux IP stack.
335
336 As said, this may be a rare case. Besides, most applications
337 can deal with a duplicate reception of the same packet. But if
338 you're a purist and want everything to work correct, you should
339 leave "CapturePacketsOnOlsrInterfaces" to its default value "no".
340
341 A disadvantage of leaving "CapturePacketsOnOlsrInterfaces" to its
342 default value "no" is that all multicast traffic must go via the
343 BMF network interface "bmf0". However, this should not be a problem,
344 since a route to all multicast addresses via the BMF network
345 interface "bmf0" is automatically added when BMF is started.
346
347
348 7. Adding non-OLSR interfaces to the multicast flooding
349 -------------------------------------------------------
350
351 As a special feature, it is possible to also forward from and to
352 non-OLSR interfaces.
353
354 If you have network interfaces on which OLSR is *not* running, but you *do*
355 want to forward multicast and local-broadcast IP packets, specify these
356 interfaces one by one as "NonOlsrIf" parameters in the BMF plugin section
357 of /etc/olsrd.conf. For example:
358
359   LoadPlugin "olsrd_bmf.so.1.7.0"
360   {
361     # Non-OLSR interfaces to participate in the multicast flooding
362     PlParam     "NonOlsrIf"  "eth2"
363     PlParam     "NonOlsrIf"  "eth3"
364   }
365
366 If an interface is listed both as "NonOlsrIf" for BMF, and in the
367 Interfaces { ... } section of olsrd.conf, it will be seen by BMF
368 as an OLSR-enabled interface.
369
370
371 8. Interworking with other multicast routers
372 --------------------------------------------
373
374 In a typical interworking configuration there is a network of OLSR hosts
375 in which one host acts as a gateway to a fixed infrastructure network.
376 Usually that host will be advertising a default route via the HNA
377 mechanism, e.g. by adding the following lines to its /etc/olsrd.conf
378 file:
379
380   Hna4
381   {
382   #   Internet gateway:
383       0.0.0.0      0.0.0.0
384   }
385
386 Alternatively, the gateway is running OLSRDs dynamic internet gateway
387 plugin; read the file ../../lib/dyn_gw/README_DYN_GW .
388
389 The gateway host will usually have at least one OLSR-interface, and
390 at least one non-OLSR interface, running a third-party routing protocol
391 like OSPF.
392
393 It is beyond the scope of this document to deal with the interworking
394 between BMF and all possible multicast routing daemons. As an example,
395 let's assume the gateway is running the mrouted multicast daemon (which
396 implements the DVMRP protocol). Also, assume that all the IP addresses
397 in the OLSR network are within the IP subnet 10.0.0.0/8 . Then mrouted
398 on the gateway needs to be configured to accept IGMP requests from IP
399 clients within the 10.0.0.0/8 subnet on the BMF network interface
400 ("bmf0"). This is easily configured by adding a line to the
401 /etc/mrouted.conf configuration file:
402
403   phyint bmf0 altnet 10.0.0.0/8
404
405 Not strictly necessary, but clean, is to disable the DVMRP protocol
406 on the OLSR interfaces, as no DVMRP routers are expected inside the
407 OLSR network. Suppose the gateway is running OLSR on "eth1", then
408 add the following line /etc/mrouted.conf :
409
410   phyint eth1 disable
411
412 Finally, mrouted does not accept interfaces with prefix length 32.
413 Therefore, override the default IP address and prefix length of
414 the BMF network interface, by editing the /etc/olsrd.conf file.
415 For example:
416
417   LoadPlugin "olsrd_bmf.so.1.7.0"
418   {
419       PlParam "BmfInterfaceIp" "10.10.10.4/24"
420   }
421
422 Note that it is not necessary, and even incorrect, to pass the
423 non-OLSR interface to BMF as a "NonOlsrIf" parameter in the
424 "LoadPlugin" section of the gateway host. When the mrouted
425 multicast daemon is running, the forwarding of multicast traffic
426 between the OLSR interface and the non-OLSR interface is done by
427 the Linux kernel.
428
429 The remaining text in this section has nothing to do with BMF or
430 OLSR, but is added to give a number of helpful hints you might
431 need when your multicast interworking, for some reason, is not working.
432
433 When using the mrouted multicast daemon, there is a useful command,
434 mrinfo, that gives information about what mrouted thinks of its
435 neighbor hosts. For example:
436
437   root@node-4:/# mrinfo
438   127.0.0.1 (localhost.localdomain) [DVMRPv3 compliant]:
439     10.1.2.4 -> 10.1.2.2 (10.1.2.2) [1/1/querier]
440     10.0.6.4 -> 0.0.0.0 (local) [1/1/disabled]
441     10.255.255.253 -> 0.0.0.0 (local) [1/1/querier/leaf]
442
443 In this example, the line starting with "10.1.2.4" is for the
444 non-OLSR interface "eth0", on which mrouted has found an
445 mrouted-neighbor host "10.1.2.2". The next line is for the OLSR
446 interface "eth1", which is disabled for mrouted. The last line
447 is for the BMF interface "bmf0". It is clear that mrouted sees no
448 mrouted-neighbors on that interface (leaf).
449
450 To see what multicast traffic has flown through the gateway, view
451 the files /proc/net/ip_mr_vif and /proc/net/ip_mr_cache:
452
453   root@node-4:/# cat /proc/net/ip_mr_vif
454   Interface      BytesIn  PktsIn  BytesOut PktsOut Flags Local    Remote
455    0 eth0          27832      98     14200      50 00000 0402010A 00000000
456    2 bmf0          14484      51     13916      49 00000 FDFFFF0A 00000000
457   root@node-4:/# cat /proc/net/ip_mr_cache
458   Group    Origin   Iif     Pkts    Bytes    Wrong Oifs
459   4D4237EA C747010A 0         51    14484        0  2:1
460   4D4237EA C702010A 0         51    14484        0  2:1
461   4D4237EA C84C000A 2         53    15052        0  0:1
462
463 From the above we can deduce that traffic from input interface 0
464 (Iif 0, "eth0") is forwarded on output interface 2 (Oifs 2, = "bmf0"),
465 and traffic from input interface 2 (Iif 2, "bmf0") is forwarded on
466 output interface 0 (Oifs 0, "eth0"). The ":1" behind the Oifs numbers
467 indicates the TTL thresholds, in this case packets with TTL value 1
468 or less will not be forwarded.
469
470 Note that when you are connecting an OLSR-BMF network to another multicast
471 network (e.g. a DVMRP-mrouted network), you might be surprised that, when
472 you ping the all-routers multicast address 224.0.0.1 from within the OLSR
473 network, only the OLSR hosts respond. This is, however, compliant behaviour:
474 packets with their destination IP address in the range 224.0.0.0 -
475 224.0.0.255 are not routed by normal multicast protocols (i.e. their
476 TTL is implicitly assumed to be 1). It doesn't mean that multicast is
477 not working; if your application uses a multicast address outisde the
478 range 224.0.0.0 - 224.0.0.255, it should work.
479
480
481 9. Common problems, FAQ
482 ------------------------
483
484 ---------
485 Question:
486 On which platforms does BMF currently compile?
487
488 Answer:
489 Only on Linux. No compilation on Windows (yet). The oldest Linux
490 kernel on which the BMF plugin was tested was version 2.4.18.
491
492
493 ---------
494 Question:
495 When starting OLSRD with the BMF plugin, I can see the following
496 error message:
497
498 OLSRD Basic Multicast Forwarding (BMF) plugin: error opening /dev/net/tun: No such file or directory
499
500 Wat to do?
501
502 Answer:
503 Turn on the possibility to create a tuntap interface; see section 2 of this
504 file.
505
506
507 ---------
508 Question:
509 When starting OLSRD with the BMF plugin, I can see the following
510 error message:
511
512 OLSRD Basic Multicast Forwarding (BMF) plugin: error opening /dev/net/tun: No such device
513
514 Wat to do?
515
516 Answer:
517 First, turn on the possibility to create a tuntap interface; see section 2 of this
518 file. Check if the device is there:
519  
520   ~ # ls -l /dev/net/tun
521   crw-------    1 root     root      10, 200 Sep  9  2006 /dev/net/tun
522
523 If the device is there, but the error message remains to appear, the
524 tap/tun device is not compiled in your kernel. Try the command:
525
526   modprobe tun
527
528 If "modprobe tun" says something like "modprobe: Can't locate module tun", then either
529 it is not compiled at all or it is not compiled into the kernel. 
530
531 Note: if you do not want to receive multicast packets, only forward the packets
532 that other hosts send, then you do not need the tuntap interface. This could be the
533 case if your host is purely an OLSR router; normally no traffic will be directed
534 to the router itself. In that case you can ignore this error message. Beware, though,
535 that you will then not be able to do the simple 'ping 224.0.0.1' test (as described in
536 section 4. How to check if it works) to check for the presence of all OLSR-BMF routers
537 in the network. 
538
539
540 ---------
541 Question:
542 I have enabled BMF, but my multicast application is not receiving any
543 multicast packets.
544
545 Answer:
546 Many multicast applications must be configured to listen to a specific
547 network interface. Make sure that your multicast application is listening on
548 the BMF network interface, either by specifying the interface name itself
549 (e.g. "bmf0") or by specifying its IP address.
550
551
552 10. Version history
553 -------------------
554
555 21 March 2010: Version 1.7.0
556
557 * Ported 1.6.2 back into OLSRd for 0.5.7.0 release: the BMF functions are
558   registered with OLSR so that a separate thread for BMF to run in is no longer
559   necessary. This also removes the need for a mutex to guarantee safe access to
560   OLSR data. Done by Henning Rogge <hrogge@googlemail.com>.
561 * Code Cleanup: duplicate code moved to separate functions
562   'ForwardPacket (...)' and 'EncapsulateAndForwardPacket (...)'
563 * Prevent the calling of 'sendto' when that would lead to blocking the
564   thread --> thanks to Daniele Lacamera for finding and solving this issue.
565 * Changed the legal range of the 'FanOutLimit' plugin parameter from 1...10
566   to 0...10 .
567
568 23 November 2008: Version 1.6.2
569
570 * Fixed a bug that prevented the route for multicast traffic to be updated
571   when a network interface was added at runtime --> thanks to Daniele Lacamera
572   for finding and solving this bug.
573
574 22 July 2008: Version 1.6.1
575
576 * Introduced a mutex for safe access to the OLSR data by the BMF thread.
577
578 4 July 2008: Version 1.6
579
580 * Fixed a bug in the CreateInterface() function: missing initialization
581   of newIf->next to NULL.
582
583 24 February 2008: Version 1.5.3
584
585 * Fixed a bug so that dying or dead end edges are not taken into account.
586   As of OLSRd version 0.5.4 , stale TC entries are not cleaned up, but
587   marked with a flag OLSR_TC_EDGE_DOWN. This flag was not taken into account
588   by BMF.
589
590 7 December 2007: Version 1.5.2
591
592 * Fixed a bug that would cause BMF to always send encapsulated broadcast
593   packets twice --> thanks to Frank Renwick and Joseph Giovatto for finding
594   this bug :-)
595 * Added the plugin parameters "BroadcastRetransmitCount" and "FanOutLimit";
596   thanks to Frank and Joe for the idea.
597
598 3 September 2007: Version 1.5.1
599
600 * Fixed a bug that would cause BMF to crash (and OLSR with it) if a link
601   was timing out --> thanks to Frank Renwick
602 * Fixed bug in the checking of the packet length --> thanks to Frank Renwick
603 * Fixed a bug in shutdown, which cause a crash if the BMF thread was not
604   yet running --> thanks to Bernd Petrovitsch
605 * Updated to OLSR plugin interface version 5.
606
607 16 May 2007: Version 1.5
608
609 * Improved packet history list to take into account the full 32 bits
610   of the packet fingerprint.
611   Previous versions derived a 16-bits value from the 32-bits packet
612   fingerprint and used that 16-bits value to determine packet unicity. In
613   situations with high packet rates (e.g. multicast video), this leads to
614   packets being incorrectly seen as duplicates of other, previously received
615   packets.
616
617 * New encapsulation format. In previous versions, a complete Ethernet
618   frame was encapsulated. This is unnecessary, and not very clean; e.g.
619   from packets coming in on non-Ethernet media such as PPP, the data in
620   the Ethernet header is bogus.
621   The new encapsulation format encapsulates only the IP packet. An
622   outer IP header [1], UDP header [2] and BMF Encapsulation Header are
623   inserted before the datagram's existing IP header, as follows:
624
625                                        +---------------------------+
626                                        |                           |
627                                        |      Outer IP Header      |
628                                        +---------------------------+
629                                        |                           |
630                                        |        UDP Header         |
631                                        +---------------------------+
632                                        |      BMF Encapsulation    |
633                                        |           Header          |
634    +---------------------------+       +---------------------------+
635    |                           |       |                           |
636    |         IP Header         |       |         IP Header         |
637    +---------------------------+ ====> +---------------------------+
638    |                           |       |                           |
639    |         IP Payload        |       |         IP Payload        |
640    |                           |       |                           |
641    |                           |       |                           |
642    +---------------------------+       +---------------------------+
643
644   The BMF encapsulation header has a typical type-length-value (TLV)
645   format:
646
647     0                   1                   2                   3
648     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
649    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
650    |     Type      |    Length     |            Reserved           |
651    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
652    |                       Packet fingerprint                      |
653    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
654
655    Type                1
656
657    Length              6.  Length in bytes of this extension, not
658                        including the Type and Length bytes.
659
660    Reserved            Reserved for future use. MUST be set to 0 on
661                        sending, MUST be verified as 0 on receipt;
662                        otherwise the extension must be handled as not
663                        understood and silently skipped.
664
665    Packet fingerprint  32-bits unique fingerprint inserted by the
666                        encapsulator. MAY be used by the receiver to
667                        determine duplicate packet reception.
668
669   The new encapsulation format is incompatible with those of previous
670   BMF versions, implying that all network nodes need to be updated.
671
672
673 31 Mar 2007: Version 1.4
674 * Optimized the standard forwarding mechanism in such a way that
675   retransmissions of packets are only done on those network interfaces
676   that make a host a multi-point relay (MPR) for the sender. I.e.:
677   retransmitting a packet on a network interface is not done if that
678   does not lead to any new hosts being reached.
679 * Optimized the standard forwarding mechanism such that, if the network
680   topology indicates there is only one neighbor on an interface, packets are
681   sent to the specific IP address (unicast) of that neighbor. If the network
682   topology indicates there are multiple neighbors, then BMF will still send
683   packets to the IP local-broadcast address.
684 * Introduced a new forwarding mechanism, using only IP-unicast to
685   forward packets. Packets are forwarded to the best candidate neighbor;
686   other neighbors listen promiscuously. IP-local broadcast is not used.
687   This saves air time on 802.11 WLAN networks, on which unicast packets are
688   usually sent at a much higher bit rate than broadcast packets (which are
689   sent at a basic bit rate).
690   This mechanism can be activated by specifying the following plugin
691   parameter:
692     PlParam "BmfMechanism" "UnicastPromiscuous"
693   See also section 6 - Advanced configuration.
694
695 18 Dec 2006: Version 1.3
696 * Added the possibility to configure the BMF network interface:
697   name (e.g. "bmf0"), type (tun or tap), IP address and subnet
698   mask.
699 * Flooding of local broadcast packets (e.g. with destination
700   IP address 192.168.1.255) can now be turned off by configuration.
701 * When an application sends packets to the BMF network interface, BMF
702   also floods these packets over the OLSR network.
703 * Removed the TTL decrementing so that equipment connected to
704   a non-OLSR interface can still send their IGMP messages (TTL = 1)
705   to a fixed multicast router (running e.g. mrouted - DVMRP)
706   connected to a non-OLSR interface on another host in
707   the OLSR network. In this way, a whole OLSR network, including
708   its non-OLSR capable hosts, can be made multicast-routable
709   from a fixed multicast-enabled IP network.
710   For an example of such a configuration read section 8 above.
711 * Removed the check for 'IsNullMacAddress' when creating a network
712   interface object. The check was not necessary and prevented
713   BMF to work on non-ethernet interfaces such as ppp.
714 * Bug fix: in case there are multiple OLSR interfaces, when an
715   application sends packets to one OLSR interface, BMF did not
716   flood these packets via the other OLSR interfaces. This is
717   fixed. Also, packets sent to an OLSR interface are transmitted
718   on the non-OLSR interfaces.
719
720 23 Oct 2006: Version 1.2
721 * Packets to a local broadcast destination have their destination
722   IP address adapted to the subnet on which they are forwarded.
723   This makes it possible to use broadcast-based services (such as
724   NetBIOS) across different IP subnets.
725 * The code to relate fragments with their main IP packet did not
726   work when the fragment arrived earlier than the main packet.
727   This would cause fragments of BMF-packets to be falsely forwarded.
728   For now, removed the forwarding of IP fragments. (Who's using
729   IP-fragments anyway?)
730 * Packets are forwarded from one non-OLSR interface to the other
731   non-OLSR interfaces.
732 * Various small optimizations and style improvements.
733
734 12 Jul 2006: Version 1.1
735 * Major updates in code forwarding from and to non-OLSR enabled
736   network interfaces.
737 * Debug level 9 gives a better indication of what happens to each
738   handled multicast/broadcast packet. To run the olsr daemon with
739   debug level 9, run "olsrd -d 9"; if you're only interested in
740   BMF debug messages, run "olsrd -d 9 | grep -i bmf".
741 * Can now deal with network interface removal ("ifdown eth1") and
742   addition ("ifup eth1").
743 * CRC-calculation for duplicate detection is done over first 256
744   bytes in packet instead of over full packet length.
745 * CRC calculated only on captured packets, and is subsequently
746   passed on in a special OLSR-BMF encapsulation header.
747 * Deals correctly with fragmented packets
748
749 27 Apr 2006: Version 1.0.1
750 * First release.
751
752
753 11. Normative References
754 ------------------------
755
756    [1]  Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981.
757
758    [2]  Postel, J., "User Datagram Protocol", STD 6, RFC 768, August
759         1980.
760