neels has submitted this change. ( https://gerrit.osmocom.org/c/osmo-upf/+/29143 ) Change subject: improve manual: PFCP and GTP interfaces ...................................................................... improve manual: PFCP and GTP interfaces Related: SYS#5599 Change-Id: Iccb3f0f52bd5006bc94d0ca06ac5d3271ea89eb9 --- M doc/manuals/chapters/overview.adoc A doc/manuals/chapters/running.adoc 2 files changed, 208 insertions(+), 0 deletions(-) Approvals: fixeria: Looks good to me, but someone else must approve laforge: Looks good to me, approved Jenkins Builder: Verified diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc index 2b9b547..9cd7751 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 the following 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..6a6afd4 --- /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-upf* [-h|-V] [-D] [-c 'CONFIGFILE'] + +=== 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-upf.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: 5 Gerrit-Owner: neels &lt;nhofmeyr(a)sysmocom.de&gt; Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria &lt;vyanitskiy(a)sysmocom.de&gt; Gerrit-Reviewer: laforge &lt;laforge(a)osmocom.org&gt; Gerrit-Reviewer: neels &lt;nhofmeyr(a)sysmocom.de&gt; Gerrit-MessageType: merged