docs: Add documentation for gluon-mesh-batman-adv (#1810)

This adds documentation for the gluon-mesh-batman-adv package and
elaborates on its build and configuration options, as well as
the implemented multicast architecture.

Signed-off-by: Linus Lüssing <linus.luessing@c0d3.blue>

docs/index.rst

@@ -64,6 +64,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
    package/gluon-ebtables-limit-arp
    package/gluon-ebtables-source-filter
    package/gluon-hoodselector
+   package/gluon-mesh-batman-adv
    package/gluon-radv-filterd
    package/gluon-scheduled-domain-switch
    package/gluon-web-admin

docs/package/gluon-ebtables-limit-arp.rst

@@ -21,3 +21,9 @@ However it mitigates the impact on the mesh when a larger range of
 its IPv4 subnet is being scanned, which would otherwise result in
 a significant amount of ARP chatter, even for unused IP addresses.
 
+This package is selected by default if the installed routing
+package is gluon-mesh-batman-adv-14 or gluon-mesh-batman-adv-15.
+It can be unselected via::
+
+    GLUON_SITE_PACKAGES := \
+      -gluon-ebtables-limit-arp

docs/package/gluon-mesh-batman-adv-logo.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" version="1.1" width="931.48547" height="370.93994" id="svg4059" inkscape:version="0.48.1 r9760" sodipodi:docname="bat_v2_black.svg" inkscape:export-filename="/mnt/pandem0nium/pub/incoming/bat_logo_v2/bat_v2_black.png" inkscape:export-xdpi="90" inkscape:export-ydpi="90" style="display:inline">
+  <sodipodi:namedview pagecolor="#000000" bordercolor="#666666" borderopacity="1" objecttolerance="10" gridtolerance="10" guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="956" inkscape:window-height="1173" id="namedview9" showgrid="false" inkscape:zoom="0.88204281" inkscape:cx="466.24453" inkscape:cy="37.028713" inkscape:window-x="1920" inkscape:window-y="0" inkscape:window-maximized="0" inkscape:current-layer="layer2" fit-margin-top="0" fit-margin-left="0" fit-margin-right="0" fit-margin-bottom="0" inkscape:snap-nodes="true"/>
+  <defs id="defs4061"/>
+  <metadata id="metadata4064">
+    <rdf:RDF>
+      <cc:Work rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/>
+        <dc:title/>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g inkscape:groupmode="layer" id="layer3" inkscape:label="outline" style="display:none" transform="translate(6.26672, 5.9375)">
+    <path style="color:#000000;fill:#ffffff;stroke:none;stroke-width:4.27199984;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" d="m 483.25,-3.21875 c -6.08901,48.631979 -35.33662,91.011416 -69.21578,124.91707 -21.83485,21.38244 -47.03966,39.44335 -75.34672,51.17668 5.57969,-19.28428 1.04687,-40.97874 -11.5,-56.59375 2.45626,-29.914047 0.68927,-59.992978 -2.5,-89.78125 -15.98198,19.265018 -27.7684,41.544355 -37.5,64.5 -12.24825,-3.17862 -25.72651,-2.402049 -37.71875,0.46875 C 239.88593,74.102096 226.47693,59.077996 210.625,47.0625 c -3.34092,23.469062 -2.56561,47.559048 0.25,70.875 -6.69043,8.82966 -11.26059,19.42531 -12.0625,30.53125 -1.92921,1.3424 -3.05608,3.45019 -4.6875,0.40625 -20.84238,-21.1131 -32.59851,-48.84198 -44.9375,-75.34375 -14.85679,72.96988 -54.000466,137.54014 -93.508574,199.57505 -20.539303,31.20908 -42.388201,61.40672 -64.085176,91.86245 8.08014534,2.26279 14.376322,-5.17296 21.382238,-7.84546 48.067949,-26.0431 95.020242,-57.97999 149.805262,-67.65454 7.73822,-1.18656 15.65228,-1.74501 23.53125,-1.625 -0.16141,-13.91977 12.35539,-25.87856 26.40625,-24.625 13.02151,-0.10475 25.24921,5.06339 36.71875,10.84375 3.0761,-8.90096 9.56834,-15.98034 17.8125,-20.25 15.98458,27.53202 46.28592,42.98776 75.65932,52.75163 10.28498,3.53684 21.92146,5.33208 32.02818,7.49837 -0.72852,8.29742 2.55832,18.64745 11.71875,20.5625 7.84288,-6.18411 13.7902,-15.27395 22.59202,-19.68372 10.89918,-0.79379 21.80373,-2.64611 32.18923,-5.97253 8.1863,6.12253 18.23881,13.28825 29.03125,9.78125 0.2397,-7.80979 -2.17974,-15.60208 -1.25,-23.34375 14.60652,-14.33722 28.49903,-29.6116 39.75,-46.65625 -31.89112,0.19103 -65.39001,-1.50716 -93.6875,-17.375 12.63668,-0.24322 25.04624,3.36048 36.09375,9.40625 26.41279,-12.24594 57.54458,-3.79641 80.97725,11.3725 5.86994,3.60205 11.37305,7.64719 16.46025,12.19 36.58823,-16.89113 78.56629,-15.82385 118.11934,-12.20623 88.66214,9.36494 173.26796,44.12384 247.50566,92.70623 3.41963,1.85442 7.16209,2.95892 10.78125,4.40625 -11.75164,-20.6658 -29.05422,-37.32743 -43.5,-56.125 C 818.67884,217.58496 746.42668,149.41496 664.49937,94.602513 607.29452,55.830775 546.38636,22.78003 483.5625,-5.9375 c -0.10417,0.90625 -0.20833,1.8125 -0.3125,2.71875 z" id="path3993-5" inkscape:connector-curvature="0"/>
+  </g>
+  <g inkscape:groupmode="layer" id="layer2" inkscape:label="batman-adv" style="display:inline" transform="translate(6.26672, 5.9375)">
+    <g style="display:inline" transform="translate(-51.5312, -495.768)" id="layer1">
+      <path d="m 538.40625,495.76769 c -8.05674,66.9338 -77.31603,151.94452 -154.9375,179.84375 3.27747,-7.40037 5.09375,-15.49392 5.09375,-24 0,-14.42887 -5.21809,-27.70021 -13.96875,-38.3125 1.97025,-21.96404 1.77421,-48.67721 -1.375,-80.59375 -13.0022,16.9579 -23.30307,37.7663 -32.15625,58.78125 -6.27289,-1.8029 -12.93745,-2.78125 -19.84375,-2.78125 -7.73405,0 -15.17627,1.22854 -22.09375,3.46875 -7.42014,-13.90647 -17.47037,-28.11748 -33.78125,-41.59375 -2.4998,23.48832 -1.59267,44.90394 1.6875,63.65625 -8.2866,10.45096 -13.63544,23.35979 -12.0986,32.68414 -4.42484,0.36051 -5.23536,4.01016 -5.31948,6.88419 -19.28312,-16.49687 -32.60091,-39.15698 -47.58192,-72.16208 -13.26705,58.98947 -53.37139,142.16702 -150.5,273.75 61.55905,-33.2251 123.79671,-75.61843 182.8125,-75.78125 4.05468,-25.33145 30.1327,-32.48291 64.65625,-15.15625 4.05331,-9.20658 11.84907,-15.85762 21.59375,-20.21875 12.89223,29.16757 60.06405,56.23506 110.53125,61.78125 -2.71475,10.31567 2.48339,19.28096 6.03125,19.90625 L 457.25,806.89269 c 12.40469,-0.59384 24.70147,-2.7024 36.40625,-6.5625 8.39362,6.41285 17.71829,12.37841 24.1875,10.96875 l -1.71875,-21.125 c 13.74684,-14.03964 23.51218,-23.14064 36.6879,-41.69749 -37.60849,-0.0334 -70.29254,-4.68998 -97.84415,-24.05251 14.31376,-2.87534 30.90137,-1.2243 48.09375,7.71875 48.64496,-20.64584 97.96875,23.25 97.96875,23.25 59.36547,-28.55091 217.47867,-17.57755 366.6875,81.8125 -81.50891,-100.35408 -186.3503,-229.51108 -429.3125,-341.4375 z" id="path3993" style="color:#000000;fill:#000000;stroke:none;stroke-width:4.27199984;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" inkscape:export-filename="/home/sven/dokumente/bat_logo_v2.png" inkscape:export-xdpi="90" inkscape:export-ydpi="90" inkscape:connector-curvature="0" sodipodi:nodetypes="ccscccscccccccccccccccccccccc"/>
+      <path d="m 287.37698,691.21665 6.32487,6.0769 42.42641,-3.28299 4.04061,-10.85914 -6.08375,5.31015 -38.85662,6.0495 z" id="path4001" style="color:#000000;fill:#ffffff;stroke:none;stroke-width:1.77165353;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" inkscape:connector-curvature="0" sodipodi:nodetypes="ccccccc"/>
+      <path d="m 304.03798,658.90775 c 3.73562,-7.35256 3.37257,-7.75354 27.47128,-14.84657 15.15993,-4.46206 30.11288,-9.25782 32.38025,-2.07348 l 18.53034,-4.86774 0.54842,3.1737 -18.32114,6.49226 c -3.7905,21.99567 -3.66551,19.92566 -20.7106,21.97074 -27.63928,3.31618 -30.32837,6.17704 -39.39348,-6.06083 l -7.32361,1.01015 c -3.77481,8.34177 -0.87651,8.42602 -25.47706,7.6321 -16.18663,-0.52238 -14.20261,-0.23719 -17.22819,-15.14996 -1.35304,-6.66902 -0.33802,-7.91117 21.30347,-5.15085 17.50983,2.23334 17.19396,1.76122 21.20894,8.92319 z" id="path4003" style="color:#000000;fill:#ffffff;stroke:none;stroke-width:1.77165353;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" inkscape:connector-curvature="0" sodipodi:nodetypes="csccccsccssscc"/>
+    </g>
+  </g>
+</svg>
\ No newline at end of file

docs/package/gluon-mesh-batman-adv-multicast.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://web.resource.org/cc/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" version="1.0" width="900pt" height="600pt" id="svg2" sodipodi:version="0.32" inkscape:version="0.43" sodipodi:docname="multicast.svg" sodipodi:docbase="/home/cyberix/Desktop">
+  <metadata id="metadata5027">
+    <rdf:RDF>
+      <cc:Work rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <sodipodi:namedview inkscape:window-height="555" inkscape:window-width="822" inkscape:pageshadow="2" inkscape:pageopacity="0.0" borderopacity="1.0" bordercolor="#666666" pagecolor="#ffffff" id="base" inkscape:zoom="1" inkscape:cx="381.10844" inkscape:cy="421.95237" inkscape:window-x="83" inkscape:window-y="46" inkscape:current-layer="svg2"/>
+  <defs id="defs4">
+    <marker refX="0" refY="0" orient="auto" style="overflow:visible" id="Arrow2Lend">
+      <path d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " transform="matrix(-1.1,0,0,-1.1,5.5,0)" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" id="path3334"/>
+    </marker>
+    <marker refX="0" refY="0" orient="auto" style="overflow:visible" id="Arrow1Mstart">
+      <path d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z " transform="scale(0.4,0.4)" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" id="path3349"/>
+    </marker>
+    <marker refX="0" refY="0" orient="auto" style="overflow:visible" id="Arrow1Lstart">
+      <path d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z " transform="scale(0.8,0.8)" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" id="path3355"/>
+    </marker>
+    <marker refX="0" refY="0" orient="auto" style="overflow:visible" id="Arrow2Mend">
+      <path d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " transform="matrix(-0.6,0,0,-0.6,3,0)" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" id="path3328"/>
+    </marker>
+    <marker refX="0" refY="0" orient="auto" style="overflow:visible" id="Arrow1Mend">
+      <path d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z " transform="scale(-0.4,-0.4)" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" id="path3346"/>
+    </marker>
+    <marker refX="0" refY="0" orient="auto" style="overflow:visible" id="Arrow1Lend">
+      <path d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z " transform="scale(-0.8,-0.8)" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" id="path3352"/>
+    </marker>
+  </defs>
+  <path id="path4261" style="fill:#ff5555;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 223.53106,327.10441 C 223.53106,352.62811 202.95773,373.31911 177.57924,373.31911 C 152.20074,373.31911 131.62741,352.62811 131.62741,327.10441 C 131.62741,301.58081 152.20074,280.88981 177.57924,280.88981 C 202.95773,280.88981 223.53106,301.58081 223.53106,327.10441 z "/>
+  <path id="path4263" style="fill:#ffff33;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 1037.931,293.05631 C 1037.931,318.58001 1017.3577,339.27101 991.97924,339.27101 C 966.60074,339.27101 946.02741,318.58001 946.02741,293.05631 C 946.02741,267.53271 966.60074,246.84171 991.97924,246.84171 C 1017.3577,246.84171 1037.931,267.53271 1037.931,293.05631 z "/>
+  <path id="path4265" style="fill:#ffff33;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 632.21606,104.97986 C 632.21606,130.50353 611.64273,151.19455 586.26424,151.19455 C 560.88574,151.19455 540.31241,130.50353 540.31241,104.97986 C 540.31241,79.456184 560.88574,58.765174 586.26424,58.765174 C 611.64273,58.765174 632.21606,79.456184 632.21606,104.97986 z "/>
+  <path id="path4267" style="fill:#55ff55;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 603.64506,607.83681 C 603.64506,633.36051 583.07173,654.05151 557.69324,654.05151 C 532.31474,654.05151 511.74141,633.36051 511.74141,607.83681 C 511.74141,582.31321 532.31474,561.62221 557.69324,561.62221 C 583.07173,561.62221 603.64506,582.31321 603.64506,607.83681 z "/>
+  <path id="path4269" style="fill:#55ff55;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 903.64506,147.83696 C 903.64506,173.36063 883.07173,194.05161 857.69324,194.05161 C 832.31474,194.05161 811.74141,173.36063 811.74141,147.83696 C 811.74141,122.31328 832.31474,101.62227 857.69324,101.62227 C 883.07173,101.62227 903.64506,122.31328 903.64506,147.83696 z "/>
+  <path id="path4271" style="fill:#ffff33;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 817.93106,413.55121 C 817.93106,439.07491 797.35773,459.76591 771.97924,459.76591 C 746.60074,459.76591 726.02741,439.07491 726.02741,413.55121 C 726.02741,388.02761 746.60074,367.33661 771.97924,367.33661 C 797.35773,367.33661 817.93106,388.02761 817.93106,413.55121 z "/>
+  <path id="path4273" style="fill:#55ff55;fill-opacity:1;stroke:#000000;stroke-width:7.57058573;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 915.07406,584.97981 C 915.07406,610.50351 894.50073,631.19451 869.12224,631.19451 C 843.74374,631.19451 823.17041,610.50351 823.17041,584.97981 C 823.17041,559.45621 843.74374,538.76521 869.12224,538.76521 C 894.50073,538.76521 915.07406,559.45621 915.07406,584.97981 z "/>
+  <path id="path4277" style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:4.69999981;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 369.68244,325.81177 L 812.01072,165.86573" sodipodi:nodetypes="cc"/>
+  <path id="path4281" style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:4.69999981;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 366.80669,324.95185 L 520.83602,583.62361" sodipodi:nodetypes="cc"/>
+  <path id="path4287" style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:4.69999981;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 368.22207,325.49587 L 828.71412,568.06311" sodipodi:nodetypes="cc"/>
+  <path style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:4.69999981;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M 226.9654,327.86162 L 369.65596,325.86694" id="path1410" sodipodi:nodetypes="cc"/>
+</svg>
\ No newline at end of file

docs/package/gluon-mesh-batman-adv.rst

+gluon-mesh-batman-adv
+=====================
+
+.. image:: gluon-mesh-batman-adv-logo.svg
+   :width: 300 px
+
+B.A.T.M.A.N. Advanced (often referenced as batman-adv) is an implementation of
+the B.A.T.M.A.N. routing protocol in form of a linux kernel module operating on layer 2.
+
+Layer 2 means that all client devices will operate in the same, virtual broadcast
+domain and will see each other "as if they were connected to one giant switch".
+
+This comes with a set of advantages (like quick and economical client device roaming,
+layer 3 protocol agnosticism, broadcast/multicast). But also impediments, especially
+layer 2 multicast overhead - which Gluon tries to mitigate to achieve a certain degree
+of scalability. See :doc:`gluon-ebtables-filter-multicast` and
+:ref:`batman-adv-multicast-architecture` for details.
+
+B.A.T.M.A.N. Advanced project homepage:
+
+* https://www.open-mesh.org/projects/batman-adv/wiki/Wiki
+
+Flavours
+--------
+
+Gluon currently supports two main build flavours of batman-adv:
+
+gluon-mesh-batman-adv-15
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the recommended batman-adv flavour to use.
+
+It follows recent, upstream batman-adv releases and is flexible to new feature additions.
+
+gluon-mesh-batman-adv-14 (`batman-adv-legacy`)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`gluon-mesh-batman-adv-14`, also known as `batman-adv-legacy` or batman-adv v2013.4
+is the last batman-adv release with the batman-adv compatibility version 14, which
+was released in October 2013.
+
+With batman-adv v2014.0.0 a compat breakage became necessary for the introduction
+of new features. However, one of these features was the addition of TVLV support
+(type-version-length-value fields) which from then on allowed adding features
+without breaking packet format compatibility. This made it possible to stay with
+compatibility version 15 so far.
+
+For new installations `gluon-mesh-batman-adv-14` is **not recommended**. It misses
+a lot of bugfixes and is currently only available for existing communities
+until they have migrated. This package will soon be deprecated and removed.
+
+Also see:
+
+* https://www.open-mesh.org/projects/batman-adv/wiki/Compatversion
+* https://www.open-mesh.org/news/56
+* https://github.com/freifunk-gluon/batman-adv-legacy/
+
+
+B.A.T.M.A.N. Routing Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For the `gluon-mesh-batman-adv-15` package two routing algorithms are selectable
+via :ref:`site.conf mesh section <user-site-mesh>`: BATMAN_IV and BATMAN_V.
+
+For the `gluon-mesh-batman-adv-14` package, BATMAN_IV_LEGACY needs to be selected.
+
+BATMAN_IV - stable
+""""""""""""""""""
+
+This is the recommended algorithm to use with `gluon-mesh-batman-adv-15`.
+
+BATMAN_V - experimental
+"""""""""""""""""""""""
+
+This is the experimental B.A.T.M.A.N. routing algorithm. It is packet format /
+compatibility stable but is still in development.
+
+For more details, see:
+
+* https://www.open-mesh.org/projects/batman-adv/wiki/BATMAN_V
+
+.. _batman-adv-multicast-architecture:
+
+Multicast Architecture
+----------------------
+
+.. image:: gluon-mesh-batman-adv-multicast.svg
+   :width: 300 px
+
+While generally broadcast capability is a nice feature of a layer 2
+mesh protocol, it quickly reaches its limit.
+
+For meshes with about **50 nodes / 100 clients, or more** it is therefore highly
+recommended to add the :doc:`gluon-ebtables-filter-multicast`
+package. Also, with gluon-mesh-batman-adv-15 or gluon-mesh-batman-adv-14
+installed :doc:`gluon-ebtables-limit-arp` is selected by default.
+
+Furthermore, by default IGMP and MLD messages are filtered. See
+:ref:`site.conf mesh section <user-site-mesh>` and
+:ref:`igmp-mld-domain-segmentation` for details.
+
+To achieve some level of scalabilty for multicast, multicast group
+awareness is implemented and utilized in the following ways:
+
+Node-Local Multicast Handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: gluon-mesh-batman-adv-multicast-architecture-to-clients.svg
+
+A Gluon node sends IGMP/MLD Queries with the following parameters on its
+local segment:
+
+* Interval: 20 seconds
+* Robustness: 9
+* Query Response Interval: 5 seconds
+
+This way, through the returning IGMP/MLD reports, the node learns which
+multicast groups its clients are interested in.
+
+This is then used to deliver multicast packets to its own Wifi clients
+via individual Wifi unicast transmissions instead of a broadcast transmission.
+
+The advantages of this are:
+
+* Usually higher bitrates: Mostly lower airtime usage
+* Acknowledged, retried transmissions (ARQ): Higher reliability
+* If no local client is interested: Avoiding the transmission, no airtime usage
+
+Notably multicast for IPv6 Neighbor Discovery usually has only a single
+multicast listener in the case of address resolution and usually no
+multicast listener for duplicate address detection. Which are the ideal
+cases for multicast snooping / multicast to unicast.
+
+The unicast delivery is achieved through utilizing the multicast-to-unicast
+feature in OpenWrt/netifd. Which in turn utilizes the multicast-to-unicast
+conversion and hairpin features of the Linux bridge, plus the hostapd client
+isolation feature, to hand over full delivery control to the bridge.
+
+Mesh-wide Multicast Handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: gluon-mesh-batman-adv-multicast-architecture-to-mesh.svg
+
+To be able to avoid transmissions not only on the "last mile", the AP interface
+to the local clients, but also from the "last mile" into the mesh in the future
+multicast listener state is propagated through the mesh:
+
+batman-adv (compat 15) taps into the Linux bridge and inherits the multicast
+groups into its translation table. Which then takes care of efficiently
+distributing this knowledge to other nodes.
+
+While by that the receiver side is ready to go, the sender part in batman-adv
+is disabled for now in Gluon. It will be enabled in a future release.
+
+.. _igmp-mld-domain-segmentation:
+
+IGMP/MLD Domain Segmentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: gluon-mesh-batman-adv-multicast-architecture-segmentation.svg
+
+Internet Group Membership Protocol and Multicast Listener Discovery Protocol
+are the standardized network protocols to query, report and learn multicast
+group memberships on the local link for IPv4 (IGMP) and IPv6 (MLD).
+
+By default Gluon filters IGMP and MLD queries and reports towards the mesh
+and runs an IGMP/MLD querier on each node for its own local clients.
+Furthermore Gluon tags the mesh side bridge port (bat0) as a multicast
+router port.
+
+That way, even though the Linux client bridge in Gluon is unable to learn
+about multicast memberships behind other nodes, the multicast router port
+flag will force it to unconditionally hand over all multicast packets to
+batman-adv. Which even with IGMP/MLD filtered, will have full multicast
+membership knowledge through its own propagation through the batman-adv
+translation table.
+
+Advantages are:
+
+* Reduced overhead through reactive batman-adv multicast TT vs.
+  periodic IGMP/MLD messages in the mesh
+* Increased IGMP/MLD snooping robustness via local, per node
+  IGMP/MLD queriers
+* DDoS vector mitigation
+
+**Note:** For nodes running an operating system other than Gluon, but a bridge
+interface on top of the batman-adv interface, you will need to set the
+multicast router flag there manually:
+
+``debian$ echo 2 > /sys/class/net/bat0/brport/multicast_router``
+
+"2" for this parameter means to always assume a multicast router behind
+this bridge port and to therefore forward all multicast packets to this
+port. Versus the default of "1" which means to learn about multicast
+routers via IGMP/MLD Queries, PIM and MRD messages; or "0" to always
+assume that there is no multicast router behind this port, meaning
+to only forward multicast to this port if an according multicast
+listener on this link was detected.
+
+Alternatively, the filtering of IGMP/MLD reports can be disabled via
+the site.conf (which is not recommended in large meshes though).
+See :ref:`site.conf mesh section <user-site-mesh>` for details.

docs/user/site.rst

@@ -224,7 +224,8 @@ mesh
     Gluon generally segments layer-2 meshes so that each node becomes IGMP/MLD
     querier for its own local clients. This is necessary for reliable multicast
     snooping. The segmentation is realized by preventing IGMP/MLD queries from
-    passing through the mesh.
+    passing through the mesh. See also
+    :ref:`gluon-mesh-batman-adv <igmp-mld-domain-segmentation>` for details.
 
     By default, not only queries are filtered, but also membership report and
     leave packets, as they add to the background noise of the mesh. As a