neels has uploaded this change for review. (
https://gerrit.osmocom.org/c/osmo-upf/+/29143 )
Change subject: improve manual: PFCP and GTP interfaces
......................................................................
improve manual: PFCP and GTP interfaces
Change-Id: Iccb3f0f52bd5006bc94d0ca06ac5d3271ea89eb9
---
M doc/manuals/chapters/overview.adoc
A doc/manuals/chapters/running.adoc
2 files changed, 208 insertions(+), 0 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/osmo-upf refs/changes/43/29143/1
diff --git a/doc/manuals/chapters/overview.adoc
b/doc/manuals/chapters/overview.adoc
index 2b9b547..c6d9671 100644
--- a/doc/manuals/chapters/overview.adoc
+++ b/doc/manuals/chapters/overview.adoc
@@ -22,3 +22,160 @@
- 1000 modifications of tunnel state per second (add/remove/modify),
- 4-8 Gbps throughput,
- 100-125k concurrent GTP tunnels.
+
+A typical network scenario using OsmoUPF is illustrated in the following
+diagram:
+
+.Typical network architecture used with OsmoUPF
+[graphviz]
+----
+digraph G {
+ rankdir = LR;
+
+ UE [label="UE\n(3G phone)"]
+
+ subgraph cluster_hnbgw_mgw_upf {
+ style=dotted
+ HNBGW -> UPF [label="PFCP",constraint=false]
+ UPF [label=OsmoUPF,style=bold]
+ }
+
+ subgraph cluster_hnbgw_mgw_upf2 {
+ style=dotted
+ SGSN -> UPF2 [label="PFCP",constraint=false]
+ UPF2 [label=OsmoUPF,style=bold]
+ }
+
+ subgraph cluster_hnbgw_mgw_upf3 {
+ style=dotted
+ GGSN -> UPF3 [label="PFCP",constraint=false]
+ UPF3 [label=OsmoUPF,style=bold]
+ }
+
+ hNodeB [shape="box",label="hNodeB\n(3G femto cell)"]
+
+ UE -> hNodeB [label="Uu"]
+ hNodeB -> HNBGW [label="Iuh",style=dashed]
+ STP [label="STP\n(SCCP/M3UA)"]
+ HNBGW -> STP -> SGSN [label="IuPS",style=dashed]
+ SGSN -> GGSN [label="GTP-C",style="dashed"]
+ hNodeB -> UPF -> UPF2 -> UPF3 [label="GTP-U"]
+ UPF3 -> internet [label="apn"]
+}
+----
+
+NOTE: at the time of writing this section, the only Osmocom component providing
+a PFCP CPF interface is OsmoHNBGW. PFCP support has not yet made its way into
+OsmoSGSN nor OsmoGGSN.
+
+=== the PFCP interface
+
+PFCP is specified by 3GPP TS 29.244.
+
+OsmoUPF implements a PFCP User Plane Function interface, listening for PFCP
+requests from PFCP Control Plane Function clients, to carry out proxy-relaying
+and encapsulation/decapsulation of GTP tunnels.
+
+OsmoUPF does not support the complete PFCP feature set. It detects exactly two
+use cases that will provide service of actual GTP tunnels:
+
+* GTP tunnel encapsulation/decapsulation:
+ - One Packet Detection Rule (PDR) accepts a GTP tunnel from the Access side
+ with an Outer Header Removal.
+ - This PDR uses a Forwarding Action Rule (FAR) for plain IP towards Core.
+ - Another PDR accepts plain IP on a specific IP address from Core.
+ - The second PDR uses a FAR towards Access with Outer Header Creation for
GTP.
+
+* GTP tunnel forwarding:
+ - One Packet Detection Rule (PDR) accepts a GTP tunnel from the Access side
+ with an Outer Header Removal.
+ - This PDR uses a Forwarding Action Rule (FAR) towards Core with an Outer
+ Header Creation for GTP.
+ - A second PDR+FAR pair like above, with Access and Core swapped.
+
+Any set of rules only partially or not at all matching the above PDR and FAR
+rules will not result in any actions on the GTP user plane, but will still
+return a successful outcome in the PFCP messages.
+
+For example, a rule set using an interface other than "Access" or "Core"
results
+in a PFCP no-op, returning PFCP responses with successful outcome, but not
+providing any GTP-U service.
+
+This is a direct result of:
+
+- allowing PFCP rule sets to be setup incrementally by several subsequent PFCP
+ messages, and of
+- OsmoUPF using Linux kernel features for the GTP user plane, where there is
+ either a full bidirectional GTP tunnel in place or none at all.
+
+For example, a typical CPF will first establish a PFCP session with the UPF
+before passing on a data service request from Access to Core, because the UPF
+must first choose the GTP TEID that needs to be forwarded towards Core. When
the
+Core side has responded with its GTP details, the UPF is updated, to form a
+complete PFCP rule set.
+
+.Typical sequence of establishing a GTP-U tunnel relay
+["mscgen"]
+----
+msc {
+ hscale="1";
+
sgsn[label="SGSN"],sgwc[label="SGW-C"],sgwu[label="SGW-U"],pgwc[label="PGW-C"];
+
+ sgsn << pgwc [label="Access"];
+ sgsn >> pgwc [label="Core"];
+
+ sgsn => sgwc [label="GTP Create Session Request\n\n\n"];
+
+ |||;
+
+ sgwc => sgwu [label="PFCP Session Establishment Request\n\n2x Create
PDR\nF-TEID = CHOOSE"];
+
+ |||;
+
+ sgwc <= sgwu [label="PFCP Session Establishment Response\n\n2x Created
PDR\nwith chosen F-TEID"];
+
+ |||;
+
+ sgwc => pgwc [label="GTP Create Session Request"];
+ sgwc <= pgwc [label="GTP Create Session Response"];
+
+ |||;
+
+ sgwc => sgwu [label="PFCP Session Modification Request\n\nUpdate
FAR\nwith F-TEID from Core"];
+
+ |||;
+
+ sgwc <= sgwu [label="PFCP Session Modification Response\n\n\n"];
+
+ |||;
+
+ sgsn <= sgwc [label="GTP Create Session Response\n\n\n"];
+}
+----
+
+The OsmoUPF logging as well as the VTY interface yield information on whether a
+ruleset results in an actual bidirectional GTP tunnel being set up.
+
+
+=== the GTP interface
+
+OsmoUPF requires Linux kernel features to provide the GTP user plane
+functionality:
+
+- the Linux kernel GTP module for encapsulation/decapsulation between GTP and
+ plain IP.
+- the Linux netfilter nftables feature for relaying GTP, i.e. forwarding
between
+ two GTP tunnels.
+
+Tunnel relaying with netfilter requires at least Linux kernel 5.17.
+
+To be able to interact with these Linux kernel features, the osmo-upf binary
+needs cap_net_admin privileges, as in:
+
+----
+sudo setcap cap_net_admin+pe /usr/bin/osmo-upf
+----
+
+Without above Linux kernel features, or when no cap_net_admin is available,
+OsmoUPF is only useful for testing PFCP clients: the GTP features may be run in
+mockup mode, so that OsmoUPF serves as a "dry run" PFCP server.
diff --git a/doc/manuals/chapters/running.adoc
b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..c01b4d0
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,51 @@
+== Running OsmoUPF
+
+The OsmoUPF executable (`osmo-upf`) offers the following command-line
+arguments:
+
+=== SYNOPSIS
+
+*osmo-hnbgw* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e
'LOGLEVEL']
+
+=== OPTIONS
+
+*-h, --help*::
+ Print a short help message about the supported options
+*-V, --version*::
+ Print the compile-time version number of the OsmoHNBGW program
+*-D, --daemonize*::
+ Fork the process as a daemon into background.
+*-c, --config-file 'CONFIGFILE'*::
+ Specify the file and path name of the configuration file to be
+ used. If none is specified, use `osmo-msc.cfg` in the current
+ working directory.
+
+=== Multiple instances
+
+Running multiple instances of `osmo-upf` on the same computer is possible if
+all interfaces (VTY, CTRL, PFCP) are separated using the appropriate
+configuration options. The IP based interfaces are binding to local host by
+default. In order to separate the processes, the user has to bind those
+services to different ports, or different specific IP addresses.
+
+The VTY and the Control interface can be bound to IP addresses from the
loopback
+address range, for example:
+
+----
+line vty
+ bind 127.0.0.2
+ctrl
+ bind 127.0.0.2
+----
+
+The PFCP port is specified to be fixed as port 8805. Hence, each osmo-upf
+process needs to run on a distinct local interface:
+
+----
+pfcp
+ local-addr 10.9.0.2
+----
+
+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.
--
To view, visit https://gerrit.osmocom.org/c/osmo-upf/+/29143
To unsubscribe, or for help writing mail filters, visit
https://gerrit.osmocom.org/settings
Gerrit-Project: osmo-upf
Gerrit-Branch: master
Gerrit-Change-Id: Iccb3f0f52bd5006bc94d0ca06ac5d3271ea89eb9
Gerrit-Change-Number: 29143
Gerrit-PatchSet: 1
Gerrit-Owner: neels <[email protected]>
Gerrit-MessageType: newchange
