From ffc461ab3816bc6b262b6087c0a1e94766b64367 Mon Sep 17 00:00:00 2001 From: Neels Janosch Hofmeyr Date: Sat, 17 Sep 2022 16:24:17 +0200 Subject: [PATCH] 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 | 119 +++++++++++++++++++++++++ doc/manuals/chapters/upf_gtp_roles.dot | 31 +++++++ 2 files changed, 150 insertions(+) create mode 100644 doc/manuals/chapters/upf_gtp_roles.dot diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc index 6a6afd4..0459541 100644 --- a/doc/manuals/chapters/running.adoc +++ b/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 +---- diff --git a/doc/manuals/chapters/upf_gtp_roles.dot b/doc/manuals/chapters/upf_gtp_roles.dot new file mode 100644 index 0000000..12dd171 --- /dev/null +++ b/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] +}