User Plane Gateway (UPG) based on VPP

UPG implements a GTP-U user plane based on 3GPP TS 23.214 and 3GPP TS 29.244 Release 15. It is implemented as an out-of-tree plugin for FD.io VPP.

The possible uses for UPG are:

• User Plane Function (UPF) in 5G networks
• Packet Data Network Gateway User plane (PGW-U)
• Traffic Detection Function User plane (TDF-U)

Current State

UPG is used in production in conjunction with erGW as GGSN/PGW in multiple installation in several telecom operators (Tier 1 and smaller).

Working features

• PFCP protocol
  • en/decoding of most IEs
  • heartbeat
  • node related messages
  • session related messages
• Uplink and Downlink Packet Detection Rules (PDR) and Forward Action Rules (FAR) -- (some parts)
• IPv4 -- inner and outer
• IPv6 -- inner and outer
• Usage Reporting Rules (URR)
• PFCP Session Reports
• Linked Usage Reports

No yet working

• Buffer Action Rules (BAR)
• QoS Enforcement Rule (QER)

Limitations

• FAR action with destination LI are not implemented
• Ethernet bearer support

General limitations and known deficits

• Error handling in Sx procedures is weak

Development setup

Design rationale for the development environment is this:

• provide an easily reproducible development and build environment usable both on CI and locally
• provide quick commands for common tasks
• simplify bisecting against upstream VPP
• discourage downstream VPP changes, as we should make effort to upstream them

Relevant parts of the source tree layout:

• hack/ contains helper scripts most of which are wrapped in make commands
• Makefile provides user interface for the environment
• upf/ contains the source code of the plugin ¹
• upf/test/ contains the integration tests ¹
• vpp/ contains VPP source code and is not committed
• vpp-patches/ contains patches to apply to the upstream VPP code (applied automatically via git am; generated by hand with git format-patch)
• vpp.spec contains the info on VPP repo, branch and commit to use

upg/ is symlinked to the VPP plugins directory, one can just go to vpp/ directory after make update-vpp and follow upstream VPP build instructions. But, as an alternative, UPG does provide some build helpers of its own.

There's a simple dockerized environment wrapped in 'make' commands. During the development cycle, VPP is cloned into vpp/ subdirectory from an upstream repository with some of the patches applied. This is done automatically but can also be done via make update-vpp which will delete all of the changes made to vpp/ directory. You can make temporary changes under vpp/ for debugging purposes.

The "build image" which is used for the devenv is tagged with a hash of Dockerfile.build as well as VPP's external dependencies.

The following make commands are supported:

• make image-debug builds a debug UPG Docker image named upg:debug
• make image-release builds a release UPG Docker image named upg:release
• make test-debug, make test-release build VPP and run UPG integration tests in debug and release mode respectively. The compilation results are retained under vpp/
• make retest-debug, make retest-release run UPG integration tests in debug and release mode respectively without building VPP. These can be run under make test-debug / make test-release to re-run the tests quickly if there were no UPG / VPP code changes
• make ensure-build-image checks if the build image exists or can be pulled and builds it otherwise
• make update-build-image-tag updates the build image tag in .gitlab-ci.yaml and Dockerfiles according to the hash calculated from Dockerfile.build and VPP external dependencies
• make install-hooks installs git hooks in the repo which prevent the user from making commits that contain ZZZZZ: substring. This is handy for debug print like clib_warning("ZZZZZ: i %d", i);
• make update-vpp re-clones VPP into vpp/ directory
• make buildenv runs an interactive shell inside the build environment with UPG and VPP sources mounted into the container
• make e2e-debug and make e2e-release build UPG in debug and release mode respectively and run E2E tests for it. For more information, see E2E test documentation

If docker is used, one should set the following environment variable to enable wrapping the internally run commands in a docker container:

export UPG_DOCKER_BUILDENV=1

As an alternative, it’s possible to run commands such as

$ make -C vpp test TEST=test_upf V=2 EXTERN_TESTS=../../upf/test

using VPP’s usual Makefile. upf/ subdirectory is symlinked to vpp/src/plugins/upf (note though that there's an issue with VPP's test discovery mechanism, thus EXTERN_TEST=... variable is required to run the tests).

Footnotes

1. Historically, the project was named simply "UPF". There may be more UPF->UPG renames later ↩ ↩²