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 00000000..86cec18f Binary files /dev/null and b/docs/package/gluon-mesh-batman-adv-multicast-architecture.dia differ 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