From b0bfe252743a640254e0edfcf4144e68f9738d49 Mon Sep 17 00:00:00 2001
From: Martin Weinelt <mweinelt@users.noreply.github.com>
Date: Thu, 17 May 2018 02:02:15 +0200
Subject: [PATCH] docs: add package/gluon-ebtables-limit-arp (#1386)

based on package documentation, authored by T_X
https://github.com/freifunk-gluon/gluon/blob/84a6f65f02d7e36a073ba2839712f0c0bb1dda10/package/gluon-ebtables-limit-arp/Makefile#L18-L39

fixes #1383
---
 docs/index.rst                            |  1 +
 docs/package/gluon-ebtables-limit-arp.rst | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+)
 create mode 100644 docs/package/gluon-ebtables-limit-arp.rst

diff --git a/docs/index.rst b/docs/index.rst
index 9f6545e6..c745c1bc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -58,6 +58,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
    package/gluon-config-mode-domain-select
    package/gluon-ebtables-filter-multicast
    package/gluon-ebtables-filter-ra-dhcp
+   package/gluon-ebtables-limit-arp
    package/gluon-ebtables-source-filter
    package/gluon-radv-filterd
    package/gluon-web-admin
diff --git a/docs/package/gluon-ebtables-limit-arp.rst b/docs/package/gluon-ebtables-limit-arp.rst
new file mode 100644
index 00000000..5a71de19
--- /dev/null
+++ b/docs/package/gluon-ebtables-limit-arp.rst
@@ -0,0 +1,23 @@
+gluon-ebtables-limit-arp
+========================
+
+The *gluon-ebtables-limit-arp* package adds filters to limit the 
+amount of ARP requests client devices are allowed to send into the 
+mesh. 
+
+The limits per client device, identified by its MAC address, are
+6 packets per minute and 1 per second per node in total. 
+A burst of up to 50 ARP requests is allowed until the rate-limiting
+takes effect (see ``--limit-burst`` in ``ebtables(8)``).
+
+Furthermore, ARP requests for a target IP already present in the
+batman-adv DAT cache are excluded from rate-limiting, in regard 
+to both counting and filtering, as batman-adv will be able
+to respond locally without a burden for the mesh. Therefore, this
+limiter should not affect popular target IP addresses, like those
+of gateways or nameservers.
+
+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.
+