From e4ef4217119ac0388eb90382fcaa58ac8e80990c Mon Sep 17 00:00:00 2001
From: Martin Weinelt <hexa@darmstadt.ccc.de>
Date: Tue, 19 Sep 2017 22:14:57 +0200
Subject: [PATCH] docs: faq: clarify how to calculate proper mesh-vpn mtu value

---
 docs/user/faq.rst  | 81 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/user/site.rst |  5 ++-
 2 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index 40a4e521..96bc169c 100644
--- a/docs/user/faq.rst
+++ b/docs/user/faq.rst
@@ -15,3 +15,84 @@ interface. This DNS server must be announced in router advertisements (using
 on *batman-adv*. If your mesh does not have global IPv6 connectivity, you can setup
 your *radvd* not to announce a default route by setting the *default lifetime* to 0;
 in this case, the *radvd* is only used to announce the DNS server.
+
+
+What is a good MTU on the mesh-vpn
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting the MTU on the transport interface requires careful consideration, as
+setting it too low will cause excessive fragmentation and setting it too high
+may leave peers with a broken tunnel due to packet loss.
+
+Consider these key values:
+
+- Payload: Allow for the transport of IPv6 packets, by adhering to the minimum MTU
+  of 1280 Byte specified in RFC 2460
+  - and configure `MSS clamping`_ accordingly,
+  - and announce your link MTU via Router Advertisments and DHCP
+
+  .. MSS clamping: http://www.tldp.org/HOWTO/Adv-Routing-HOWTO/lartc.cookbook.mtu-mss.html
+
+- Encapsulation: Account for the overhead created by the configured mesh protocol
+  encapsulating the payload, which is
+  - up to 32 Byte (14 Byte Ethernet + 18 Byte batadv) for batman-adv compat v15 (v2014.0 and later)
+  - up to 28 Byte (14 Byte Ethernet + 14 Byte batadv) for batman-adv compat v14 (v2011.3.0 until and including v2013.4.0)
+
+- PMTU: What MTU does the path between your gateway and each of its peers support?
+
+For reference, the complete MTU stack looks like this:
+
+.. image:: https://cloud.hamburg.freifunk.net/thumbnail/de738ee3ac/1024/MTU%20within%20a%20batman-adv%20network%20v5.png
+
+Minimum MTU
+-----------
+
+Calculcate the minimum transport MTU by adding the encapsulation overhead to the
+minimum payload MTU required. This is the lowest recommended value, since going
+lower would cause unnecessary fragmentation for clients which respect the announced
+link MTU.
+
+Example: Our network currently uses batman-adv v15, it therefore requires up
+to 32 Bytes of encapsulation overhead on top of the minimal link MTU required for
+transporting IPv6.::
+
+  \        1312              1294          1280                                 0
+   \---------+-----------------+-------------+----------------------------------+
+    \TAP     |    batadv v15   |   Ethernet  |            Payload               |
+     \-------+-----------------+-------------+----------------------------------+
+      \      ^
+             |
+
+          MTU_LOW = 1280 Byte + 14 Byte + 18 Byte = 1312 Byte
+
+Maximum MTU
+-----------
+
+Calculating the maximum transport MTU is interesting, because it increases the
+throughput, by allowing larger payloads to be transported, but also more difficult
+as you have to take into account the tunneling overhead and each peers PMTU, which
+varies between providers.
+The underlying reasons are mostly PPPoE, Tunneling and IPv6 transition technologies
+like DS-Lite.
+
+Example: The peer with the smallest MTU on your network is behind DS-Lite and can
+transport IPv4 packets up to 1436 Bytes in size. Your tunnel uses IPv4 (20 Byte),
+UDP (8 Byte), Fastd (24 byte) and you require TAP (14 Byte) for Layer 2 (Ethernet)
+Tunneling.::
+
+  1436                1416     1408                    1384          1370    \
+    +-------------------+--------+-----------------------+-------------+------\
+    |        IP         |  UDP   |         Fastd         |     TAP     |    bat\
+    +-------------------+--------+-----------------------+-------------+--------\
+                                                                       ^         \
+                                                                       |
+
+       MTU_HIGH = 1436 Byte - 20 Byte - 8 Byte - 24 Byte - 14 Byte = 1370 Byte
+
+Conclusion
+----------
+
+Determining the maximum MTU can be a tedious process, especially since the PMTU
+of peers could change at any time. The general recommendation for maximized
+compatibility is therefore the minimum MTU of 1312 Byte, which works well with
+all combinations of IPv4, IPv6, batman-adv compat v14 and v15.
diff --git a/docs/user/site.rst b/docs/user/site.rst
index 0bc1744d..01d7fcf8 100644
--- a/docs/user/site.rst
+++ b/docs/user/site.rst
@@ -195,7 +195,10 @@ mesh_vpn
     Remote server setup for the mesh VPN.
 
     The `enabled` option can be set to true to enable the VPN by default. `mtu`
-    defines the MTU of the VPN interface.
+    defines the MTU of the VPN interface, determining a proper MTU value is described
+    in the FAQ entry `"What is a good MTU on the mesh-vpn?"`_.
+
+    .. _"What is a good MTU on the mesh-vpn?": faq.rst
 
     The `fastd` section configures settings specific to the *fastd* VPN
     implementation.