manual: add 'Configure Primary Links'

Add section 'Configure Primary Links' with detailed explanation of the
GTP and netfilter setup.

Related: SYS#5599
Change-Id: I2378d4856b28e81dae2a85e20aaf2999768de4d9

doc/manuals/chapters/running.adoc

@@ -49,3 +49,122 @@ pfcp
 For GTP encapsulation/decapsulation and GTP tunnel relaying, osmo-upf depends on
 the IP addresses configured at the Linux kernel GTP module, and the IP addresses
 negotiated within PFCP by the control plane function.
+
+If multiple `osmo-upf` processes are running on the same Linux kernel, each
+`osmo-upf` needs to be configured with a distinct netfilter table name, so that
+naming of individual tunnel rulesets does not collide:
+
+----
+nft
+ table-name osmo-upf-2
+----
+
+=== Configuring Primary Links
+
+==== Configure PFCP Server
+
+The following example configures OsmoUPF to listen for PFCP association requests
+from Control Plane Function entities on local interface 10.9.8.7, port 8805:
+
+----
+pfcp
+ local-addr 10.9.8.7
+----
+
+3GPP TS 29.244 4.2.2 specifies that PFCP Request messages shall be sent to UDP
+port 8805, i.e. the PFCP port is fixed as 8805 and currently not configurable in
+osmo-upf.
+
+Setting a 'local-addr' is required: the PFCP protocol features a Node ID, which
+uniquely identifies PFCP peers across different interfaces. According to the
+PFCP specification, the Node ID can be a fully-qualified domain name (FQDN) or
+an IP address. Currently, osmo-upf has no support for using an FQDN as Node
+ID, and so far uses the 'local-addr' as local Node ID -- hence the 'local-addr'
+must not be "0.0.0.0", which is an unfortunate consequence. This is likely to
+improve in the future, see https://osmocom.org/issues/5682 .
+
+==== Configure Linux Kernel GTP Features
+
+OsmoUPF uses two distinct Linux kernel features:
+
+* The GTP module is used for GTP encapsulation/decapsulation from/to
+  "the internet".
+
+* The netfilter module is used for GTP tunnel proxying, also known as
+  tunnel forwarding or tunnel mapping.
+
+.Linux kernel feature usage
+[graphviz]
+----
+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_module]]
+===== Configure Linux Kernel GTP Module
+
+The Linux kernel GTP module is used for GTP encapsulation/decapsulation from/to
+"the internet".
+
+To use the GTP kernel module, OsmoUPF requires a GTP device, which is a
+dedicated network device provided by the Linux kernel, serving as GTP tunnel
+endpoint. It is typically named like "apn0".
+
+`osmo-upf` can either create a GTP device on startup, or use a pre-existing GTP
+device. To en/decapsulate GTP, the APN device needs to be assigned an IP address
+range that matches the UE IP addresses that are configured in GTP-C / PFCP.
+
+The following configuration placed in `osmo-upf.cfg` creates a GTP device called
+`apn23` on startup, which is also destroyed on program exit:
+
+----
+gtp
+ dev create apn23
+----
+
+TODO:: `osmo-upf` is not yet able to configure this network device's IP address
+range, MTU etc.
+
+The following configuration placed in `osmo-upf.cfg` uses a pre-existing device
+called `apn42`:
+
+----
+gtp
+ dev use apn42
+----
+
+GTP kernel devices can be managed manually using the `gtp-link` program
+available from the 'libgtpnl' project:
+
+----
+# gtp-link add apn42
+(keep this process running)
+# ip addr add dev apn42 192.168.42.1/24
+
+$ osmo-upf -c osmo-upf.cfg
+----
+
+NOTE:: It is possible to configure multiple GTP devices in `osmo-upf.cfg`, but
+`osmo-upf` currently _only uses the first GTP device_ found in the
+configuration. In the future, different devices may be used based on the Network
+Instance IE passed in the PFCP Session messages (PDR/FAR). Until then, it makes
+little sense to configure more than one GTP device.
+
+[[nftables]]
+===== Configure Linux netfilter
+
+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`.
+
+`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:
+
+----
+nft
+ table-name my-table-name
+----

doc/manuals/chapters/upf_gtp_roles.dot

@@ -0,0 +1,31 @@
+digraph G {
+rankdir=LR
+sgsn [label="SGSN"]
+
+subgraph cluster_sgw {
+	style=invisible
+	sgwc [label="SGW-C"]
+	sgwu [label="OsmoUPF as SGW-U\ntunnel proxy\n*netfilter* kernel module",style=bold,shape=box]
+	sgwc -> sgwu [label="PFCP",constraint=false]
+}
+
+subgraph cluster_pgw {
+	style=invisible
+	pgwc [label="PGW-C"]
+	pgwu [label="OsmoUPF as PGW-U\ntunnel proxy\n*netfilter* kernel module",style=bold,shape=box]
+	pgwc -> pgwu [label="PFCP",constraint=false]
+}
+
+subgraph cluster_tdf {
+	style=invisible
+	tdfc [label="TDF-C"]
+	tdfu [label="OsmoUPF as TDF-U\ntunnel en-/decaps\n*GTP* kernel module",style=bold,shape=box]
+	tdfc -> tdfu [label="PFCP",constraint=false]
+}
+
+pdn [label="PDN\n'the internet'"]
+
+sgsn -> sgwc -> pgwc -> tdfc [label="GTP-C"]
+sgsn -> sgwu -> pgwu -> tdfu [label="GTP-U",dir=both]
+tdfu -> pdn [label="IP",dir=both]
+}