manual: explain GTP Echo workaround for tunmap

Change-Id: Ic824fc876d1fad181254cb6894e51464c443b53c
---
M doc/manuals/chapters/running.adoc
1 file changed, 56 insertions(+), 7 deletions(-)


git pull ssh://gerrit.osmocom.org:29418/osmo-upf refs/changes/67/35667/1

diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
index 32db271..d1a399b 100644
--- a/doc/manuals/chapters/running.adoc
+++ b/doc/manuals/chapters/running.adoc
@@ -99,10 +99,10 @@
 
 GTP kernel module configuration in the `tunend` section can be omitted for sites
 that serve only as GTP forwarding proxy, without encapsulation/decapsulation of
-GTP payloads.
+GTP payloads -- except to provide GTP Echo service, see <<gtp_echo>>.
 
-Likewise, netfilter configuration in the `tunmap` section can be omitted for
-sites only serving as GTP tunnel endpoint.
+Netfilter configuration in the `tunmap` section can be omitted for sites only
+serving as GTP tunnel endpoint.
 
 [[gtp_module]]
 === Configure Linux Kernel GTP Module for `tunend`
@@ -167,11 +167,51 @@
 The Linux kernel netfilter module is used for GTP tunnel proxying, also known as
 tunnel forwarding or tunnel mapping.
 
-Using the netfilter module usually requires no configuration in `osmo-upf.cfg`.
+When using the netfilter module, you may set up `osmo-upf.cfg` for:
+- GTP Echo (required)
+- netfilter table name (optional)
 
-`osmo-upf` creates a new netfilter table, under which it submits rule sets for
-GTP tunnel proxying. This table name defaults to `osmo-upf`. A custom table name
-can be configured in `osmo-upf.cfg` like this:
+[[gtp_echo]]
+==== GTP Echo
+
+Each GTP peer should respond directly to GTP Echo requests.
+- A GTP device configured for `tunend` implicitly includes a GTP Echo service.
+- For `tunmap`, no GTP Echo mechanism is implemented.
+
+So, when your use case is `tunmap`, you should still add a GTP device as for
+`tunend`, only to provide the GTP Echo service. There are some options:
+
+If you have no GTP devices configured in `osmo-upf.cfg` yet, you can add a
+single GTP device without a specific IP address, in order to respond to GTP-U
+Echo requests on all interfaces to anyone that is asking:
+
+----
+tunend
+ dev create gtp-echo
+----
+
+This will bind osmo-upf on 0.0.0.0:2152 to respond to GTP Echo requests.
+
+If you would like to limit GTP Echo responses to specific network interfaces,
+you need to add a separate GTP device per local IP address:
+
+----
+tunend
+ dev create gtp-echo1 192.168.0.23
+ dev create gtp-echo2 10.9.8.17
+----
+
+This will bind osmo-upf only on 192.168.0.23:2152 and 10.9.8.17:2152 to respond
+to GTP Echo requests.
+
+For creating and manipulating a GTP device in more versatile ways, see
+<<gtp_module>>.
+
+==== netfilter Table Name
+
+For `tunmap`, `osmo-upf` creates a new netfilter table, under which it submits
+rule sets for GTP tunnel proxying. This table name defaults to `osmo-upf`. A
+custom table name can be configured in `osmo-upf.cfg` like this:
 
 ----
 tunmap

