manual: explain IP forwarding

Change-Id: I7b54f9203c1a77efd43f90b9a1c0105bc5c3efde

doc/manuals/chapters/running.adoc

@@ -85,10 +85,10 @@ improve in the future, see https://osmocom.org/issues/5682 .
 
 OsmoUPF uses two distinct Linux kernel features:
 
-* The GTP module is used for GTP encapsulation/decapsulation from/to
+* The GTP module is used for `tunend`: GTP encapsulation/decapsulation from/to
   "the internet".
 
-* The netfilter module is used for GTP tunnel proxying, also known as
+* The netfilter module is used for `tunmap`: GTP tunnel proxying, also known as
   tunnel forwarding or tunnel mapping.
 
 .Linux kernel feature usage
@@ -97,8 +97,12 @@ OsmoUPF uses two distinct Linux kernel features:
 include::upf_gtp_roles.dot[]
 ----
 
-GTP kernel module configuration can be omitted for sites that serve only as GTP
-forwarding proxy, without encapsulation/decapsulation of GTP payloads.
+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 -- except to provide GTP Echo service, see <<gtp_echo>>.
+
+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`
@@ -163,11 +167,51 @@ this GTP device. When using ANY, there should be exactly one GTP dev configured.
 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 should configure:
+- 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
@@ -176,3 +220,40 @@ tunmap
 
 When running more than one osmo-upf process on a system, pick distinct table
 names to avoid name collisions in the nftables rulesets.
+
+=== IP Forwarding
+
+In order to allow the forwarding GTP payloads, the Linux operating system must
+be configured to allow IP forwarding. There are several options:
+
+To allow IP forwarding from and to all interfaces globally in a reboot-safe way,
+you may put a line like this in /etc/sysctl.conf:
+
+----
+net.ipv4.ip_forward=1
+----
+
+To do the same in an ad-hoc way that is not reboot safe but takes effect
+immediately:
+
+----
+sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
+----
+
+The above options may be too permissive for your production environment. It is
+possible to instruct netfilter to allow IP forwarding for specific interfaces
+only, with a configuration like this:
+
+----
+define gtp_netdevs = { eth0, eth23 };
+
+table inet filter {
+      chain forward {
+              type filter hook forward priority filter; policy drop;
+              iifname $gtp_netdevs oifname $gtp_netdevs udp dport 2152 accept
+      }
+}
+----
+
+This netfilter ruleset allows IP forwarding, but limited to the GTP-U port 2152,
+and to two specific network interfaces eth0 and eth23.