An open source C++ library powered by eBPF/XDP for user plane in mobile core network (5G/LTE).
The key pillars of this project are:
- In-kernel fast packet processing
- Flexible and programmable dataplane
- Portable to different systems
These points are achieved mainly by eBPF/XDP and CO-RE (Compile Once - Run Everywhere) technologies.
This project is based on the following 3GPP Technical Specification:
- LTE; 5G; Interface between the Control Plane and the User Plane nodes (3GPP TS 29.244 version 16.5.0 Release 16)
- 5G; System architecture for the 5G System (5GS) (3GPP TS 23.501 version 16.5.0 Release 16)
The main goal is to enable in-kernel fast packet processing in third-party UPF/5G or SPGWu/LTE components in order to:
- Boost them for those which does not have any fast packet processing enabled, or
- Co-locate them with other fast packet processing solutions (e.g. DPDK)
Possible scenarios that take advantage of this type of technology: MEC, 5G NPN (Non Public Networks), on-premise, 5G enterprise, and much more.
The library is divided in layers:
- Management Layer: An user space layer responsible to receive requests from the third-party UPF/SPGWu components to manage PFCP sessions and eBPF programs lifecycle
- Datapath Layer: A kernel space layer representing by eBPF/XDP programs responsible to handle the user traffic (datapath) for fast packet processing
The high level design is shown in figure below.
The library has a component, called PFCP Sesssion Manager, which is a C++ API responsible to manage PFCP (Packet Forwarding Control Protocol) sessions. For each session, there is an eBPF program that represents the PFCP context in the fast path. These programs are managed by eBPF Program Manager component. The fast path is composed by three main function: parser, traffic classifier and traffic forwarder. The image below shows this in more detail.
A low-level design (Datapath Layer) is shown below.
As described in 3GPP TS 29.244, the Information Elements (IEs) are part of the PFCP context. The PFCP context is created by sending PFCP Session Establishment Request message. The main features supported in this project are:
Management Layer - CRUD
- PFCP Session
- PDR (Packet Detection Rule)
- FAR (Forwarding Action Rule)
Fast Datapath Layer
- UDP and GTP parse
- Traffic classification based on PDR
- Traffic fowarding based on FAR
The logical data model between PFCP Session and IEs is shown in the image below. For more detail, see 3GPP TS 29.244 version 16.5.0 Release 16.
Management Layer - CRUD
- QER (QoS Enforcement Rule)
Fast Datapath Layer
- Policy Enforcement based on QER
Core
- libbpf
- bpftool
- spdlog
- clang >= version 3.4.0
- llvm >= version 3.7.1
- kernel-headers => version 5.3
- cmake >= 3.16
Test
- scapy v2.4.3
- gtest
- sysstat
- trex v2.86
First of all, make sure you have installed git-lfs. The LFS repository is used to store the bpftool binary.
After dowloaded and installed it, clone this repository:
git clone https://github.com/navarrothiago/upf-bpf.git
After cloning the repository, configure your env.sh file (on the repository root folder) to match your dev or test environment, using the .env.sample.sh file as a template
The project use a docker container to build the UPF library. The command below will provision the docker image with all the project dependencies.
📝 You'll need the Docker Container Runtime package and the Docker Compose utility to set up the dev or test environment
make docker-build
After that, run the container with:
make docker-run
You can also use the vscode development container feature to build the image and login into the container. Check here to understand how to open the devcontainer.json file.
Inside the container, compile the dependencies with
make setup
The library is built and installed with
make install
The package folder is create with the headers, library and some binaries for testing.
package
├── bin # Contains binaries for testing
├── include # Contains headers
├── lib # Contains libupf_xdp.a library
└── tests # Contains scripts for testing
The instructions here is still missing. If you need to know how to test, contact me. There is a lot of script that make the deployment and configuration easier. As you can see in .env.sample.sh, there are variables to configure the jump server, trex version, GTP and UDP interfaces (downlink and uplink), etc. Besides, there are UTs for Session Management layers. You can execute with (inside the container).
make config-veth-pair
make build-tests
make run-session-manager-tests
If you face any problem, feel free to open an issue or contact me.
Test environment:
Step:
- Run Trex Traffic Generator
- Run HTTP API + upf-bpf
- Configure interfaces (/configure)
- Create PFCP Session context (/createSession)
- Generate the traffic (pkt size = 64B)
- Collects metrics (CPU load, ipackets, opacket, throughput)
📝 Postman files are available: Uplink and Downlink. You will find the json message used by the tests.
The flows are generate using Trex Field Engine. Check the implementation here.
📝 The tmux session is available here. There are still some parameters hardcoded. Feel free to change according to your need. If you need any help, open and issue or contact me. PR are welcome!!
| Downlink | Uplink |
|---|---|
 |
 |
 |
 |
Check the Jupyter notebook to how the graphics are generated.
📝 For more graphics, check this folder.
The directory structure was created based on this notes.
├── build: Generated build directory.
├── cmake: Cmake files configuration directory
├── CMakeLists.txt: Cmake file
├── extern: Submodule repositories
├── include: Include files
├── LICENSE: File license
├── Makefile: Encapsulate cmake calls for build, run samples, clean, etc
├── README.md: Readme file
├── samples: Samples like XDP BPF hello world
└── src: Source files directory
If you faced the problem below, create a symbolic from libc.a -> liblibc.a
No such file or directory: b'liblibc.a'
If you think this could be better, please open an issue or start a discussion.
PRs ARE WELCOME 👍!!
- Discord Server
- Mail: <navarro (dot) ime (at) gmail [dot] com>
- GitHub: @navarrothiago
- Twitter: @navarr0thiag0