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
The project use a docker container to build the UPF library. The command below will provision the docker image with all the project dependencies.
make docker-build
Warning: THE SSH PRIVATE KEY IS COPIED TO THE DOCKER IMAGE. DO NOT PUSH THIS IMAGE TO THE INTERNET!!
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. For your information, there are UTs for Session Management layers. Also, you can check the video Performance Evaluation with UPF eBPF/XDP Library for 5G Core Network to see the performance evaluation (deprecated).
Check the Jupyter notebook.
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.
- Discord Server
- Mail: <navarro (dot) ime (at) gmail [dot] com>
- GitHub: @navarrothiago
- Twitter: @navarr0thiag0