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