From bce76bcaf056d36fde25ea01ade25b98c3a41bf3 Mon Sep 17 00:00:00 2001 From: T-X Date: Tue, 10 Sep 2019 23:55:06 +0200 Subject: [PATCH] docs: Add documentation for gluon-mesh-batman-adv (#1810) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/index.rst | 1 + docs/package/gluon-ebtables-limit-arp.rst | 6 + docs/package/gluon-mesh-batman-adv-logo.svg | 25 ++ ...dv-multicast-architecture-segmentation.svg | 246 ++++++++++++++++++ ...-adv-multicast-architecture-to-clients.svg | 232 +++++++++++++++++ ...man-adv-multicast-architecture-to-mesh.svg | 232 +++++++++++++++++ ...mesh-batman-adv-multicast-architecture.dia | Bin 0 -> 2248 bytes .../gluon-mesh-batman-adv-multicast.svg | 44 ++++ docs/package/gluon-mesh-batman-adv.rst | 202 ++++++++++++++ docs/user/site.rst | 3 +- 10 files changed, 990 insertions(+), 1 deletion(-) create mode 100644 docs/package/gluon-mesh-batman-adv-logo.svg create mode 100644 docs/package/gluon-mesh-batman-adv-multicast-architecture-segmentation.svg create mode 100644 docs/package/gluon-mesh-batman-adv-multicast-architecture-to-clients.svg create mode 100644 docs/package/gluon-mesh-batman-adv-multicast-architecture-to-mesh.svg create mode 100644 docs/package/gluon-mesh-batman-adv-multicast-architecture.dia create mode 100644 docs/package/gluon-mesh-batman-adv-multicast.svg create mode 100644 docs/package/gluon-mesh-batman-adv.rst diff --git a/docs/index.rst b/docs/index.rst index 60b07be3..433e302e 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/package/gluon-ebtables-limit-arp.rst b/docs/package/gluon-ebtables-limit-arp.rst index 5a71de19..e4ba6b4b 100644 --- a/docs/package/gluon-ebtables-limit-arp.rst +++ b/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 diff --git a/docs/package/gluon-mesh-batman-adv-logo.svg b/docs/package/gluon-mesh-batman-adv-logo.svg new file mode 100644 index 00000000..8c1b4267 --- /dev/null +++ b/docs/package/gluon-mesh-batman-adv-logo.svg @@ -0,0 +1,25 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/package/gluon-mesh-batman-adv-multicast-architecture-segmentation.svg b/docs/package/gluon-mesh-batman-adv-multicast-architecture-segmentation.svg new file mode 100644 index 00000000..ec1c0d37 --- /dev/null +++ b/docs/package/gluon-mesh-batman-adv-multicast-architecture-segmentation.svg @@ -0,0 +1,246 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mesh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Clients + + + + + + IGMP + MLD + Firewall + + + Query + + + Report + + + + + + + + + + + diff --git a/docs/package/gluon-mesh-batman-adv-multicast-architecture-to-clients.svg b/docs/package/gluon-mesh-batman-adv-multicast-architecture-to-clients.svg new file mode 100644 index 00000000..1d81a496 --- /dev/null +++ b/docs/package/gluon-mesh-batman-adv-multicast-architecture-to-clients.svg @@ -0,0 +1,232 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mesh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Clients + + + + + + + + + + diff --git a/docs/package/gluon-mesh-batman-adv-multicast-architecture-to-mesh.svg b/docs/package/gluon-mesh-batman-adv-multicast-architecture-to-mesh.svg new file mode 100644 index 00000000..db557d4b --- /dev/null +++ b/docs/package/gluon-mesh-batman-adv-multicast-architecture-to-mesh.svg @@ -0,0 +1,232 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mesh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Clients + + + + + + + + + + diff --git a/docs/package/gluon-mesh-batman-adv-multicast-architecture.dia b/docs/package/gluon-mesh-batman-adv-multicast-architecture.dia new file mode 100644 index 0000000000000000000000000000000000000000..86cec18fd75aada458239be49958a375a1421271 GIT binary patch literal 2248 zcmV;(2sig1iwFP!000021MOW~Z{xTXexF|dKNU$;qS-{p~%JHSt)NSe8U5X(b>rqEP3M6wk-+T$p_S!ZGC@4jCK{&(=TO8kujPeiHt>1MLdvh8=%>BGZ=8$PCf7AI~P z?A%mO|Ko?DKZQoq$%l82^R0lTpZVrqao5kXB$)3q?L_`Y-%RHI;PW0 zh{HH>?)~s)^8T*4CeuRD^hnY((zpIf&lBzc)+`*srBpZJTb+~zZ?4Rx-+r>Tb1iq31k2|Q_ozjKl;tCQ1`DgN)S7uUddkiqb2G0K^n|M zUDx{{$_5kvIE?u63dr|}!{a?y++JGaCbX2AYu;rOTJ3_RPERc6<2DVF)p3;cAl-)k5qNhI|xT#a1P0|8q^!+2-pJdy8-6D)5gzo6rVU!E1 zniS0EW%-F2T(k=HlMbeo(E=Ycs$7on6=CM1o7Roa{K*LfUIwt>J4x4}-rO$YB&w3{ z;U+FulJB6^$$Q#8MGx6)9jw+_vvAc-Hc&i$s^7@P==j1tl$o7wmsDT(u@i>SVgEZ% z$z2eJEtHhq$n%sK*t)IpR!^hV+4GfVkD)Fr(9v#FyqwAwT}#)_n!zyG-mc>$_;(y- ze)#O*N}J5tY5)PVU|~;5x|BL2tOGOc(93z1#wuted?D!f%e+2yz^j`?{ z{|2zR^phpv{;&E=Rs;5=FW6Ijg_Tt+oKi<$V3i zJPiJI?3te5lgb`Yw|ZU55Qhs<0UDOEGW;z zu&!QYd-G@-W{rISVdE_CCqdjB?c>Ql*zp=?FK!>Ly#&$QOn|yy5o$L^#Jnr83h)!S zi*i4KzjZ&M&#aA}!sscCp2FxUw539_e-^;y1S zZ#Y@jbJp6?A&$7>N=hoR$FV1@Cd`;(ND7Q7l9DLpjr?fjM{>39<0e9%*X;t|2N*Ld z-$dQ+$1u>~c8{gI7b@MYS&w7!?h6<1?tjit7uTLO&f@EhPS-sS8lR2=;@+nd2(w!d zX2Ndy=>#B7GXnIM&^*A#aMxsf>&RbeXf+K~=ds(1@|A70VxJPMQ+8%-?KmhYxF=B( z5lTqMAT7M5TR%zShwfH)O7d-}qt)|+;eAz{oGv~rt@$zjQfKSE3;)dqVyg1F-J_>0 zSHk#=!OU=z*X7*m>Ck?|YUOS!o9-pH?-%u8^=%v@JpA6d*i+15w$BEO>R(QcZQBz@ zuKH?E=Ff9nz@B;ys+Bd-UeZT<8YqX1`4E4|K-sM_mBM2O0!dtaDfUQCutzLL_BgV~ z7hsR4HqSr(@$;XjpFjP?$MWlO|+BYF)GNn<@|Qy(xp{tEhb&Xl`$qg zAUeqb`~bV?L<~AH1Y0$A6%%E!VR0SQ$A$vzMvSC)zxm~|u~mqDU2 zJ7yJ$dROb3lGFU}*xHOrfiT$0Mhh?`@eY4>6B1 zIYv$|n0Idifd1u#!j<`MKpyZ-`{gXnlpZvX%<;(ZSQ literal 0 HcmV?d00001 diff --git a/docs/package/gluon-mesh-batman-adv-multicast.svg b/docs/package/gluon-mesh-batman-adv-multicast.svg new file mode 100644 index 00000000..e130812f --- /dev/null +++ b/docs/package/gluon-mesh-batman-adv-multicast.svg @@ -0,0 +1,44 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/package/gluon-mesh-batman-adv.rst b/docs/package/gluon-mesh-batman-adv.rst new file mode 100644 index 00000000..966cd7ab --- /dev/null +++ b/docs/package/gluon-mesh-batman-adv.rst @@ -0,0 +1,202 @@ +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 `: 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 ` 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 ` for details. diff --git a/docs/user/site.rst b/docs/user/site.rst index bd4a874f..49007b65 100644 --- a/docs/user/site.rst +++ b/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 ` 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