{"id":13799754,"url":"https://github.com/navarrothiago/upf-bpf","last_synced_at":"2025-10-25T15:10:25.754Z","repository":{"id":44817324,"uuid":"274778444","full_name":"navarrothiago/upf-bpf","owner":"navarrothiago","description":"An In-Kernel Solution Based on eBPF / XDP for 5G UPF","archived":false,"fork":false,"pushed_at":"2024-09-28T13:02:41.000Z","size":1591,"stargazers_count":200,"open_issues_count":17,"forks_count":28,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-28T08:09:29.242Z","etag":null,"topics":["3gpp","5g","5g-core","5g-core-network","5gc","bpf","cmake","co-re","ebpf","flex","trex-engine","trex-traffic-generator","upf"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navarrothiago.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-24T22:05:47.000Z","updated_at":"2025-03-17T14:14:21.000Z","dependencies_parsed_at":"2023-01-23T05:46:09.818Z","dependency_job_id":"a7f6e4a6-310b-4844-813b-94733c5b2d4e","html_url":"https://github.com/navarrothiago/upf-bpf","commit_stats":{"total_commits":134,"total_committers":3,"mean_commits":"44.666666666666664","dds":0.06716417910447758,"last_synced_commit":"32ce813a6700db2b220acd333e6ae35346892c53"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navarrothiago%2Fupf-bpf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navarrothiago%2Fupf-bpf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navarrothiago%2Fupf-bpf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navarrothiago%2Fupf-bpf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navarrothiago","download_url":"https://codeload.github.com/navarrothiago/upf-bpf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767237,"owners_count":20992548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3gpp","5g","5g-core","5g-core-network","5gc","bpf","cmake","co-re","ebpf","flex","trex-engine","trex-traffic-generator","upf"],"created_at":"2024-08-04T00:01:05.776Z","updated_at":"2025-10-25T15:10:25.674Z","avatar_url":"https://github.com/navarrothiago.png","language":"C++","funding_links":[],"categories":["Projects Related to eBPF","Core","eBPF 相关项目","NFs"],"sub_categories":["Tools","5G","工具"],"readme":"🛠️ **INTEGRATION**: The project has been successfully merged and enhanced within the OAI 5G UPF component. For further details, see the [repository](https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-upf/-/tree/master/src/upf_app?ref_type=heads).\n\n📝 **NOTE**: This is an experimental project. The releases are intended for quick access to the artifacts referenced in the publications. Check the [docs](docs/) folder for more information.\n\n# 5G UPF using BPF/XDP\n\nAn open source C++ library powered by BPF/XDP for user planes in the mobile core network (5G/LTE).\n\nThe key pillars of this project are:\n\n- In-kernel fast packet processing\n- Flexible and programmable dataplane\n- Portable to different systems\n\nThese points are achieved mainly by BPF/XDP and CO-RE (Compile Once - Run Everywhere) technologies.\n\nThis project is based on the following 3GPP Technical Specification:\n- LTE; 5G; Interface between the Control Plane and the User Plane nodes (3GPP TS 29.244 version 16.5.0 Release 16)\n- 5G; System architecture for the 5G System (5GS) (3GPP TS 23.501 version 16.5.0 Release 16)\n\nThe main goal is to enable in-kernel fast packet processing in third-party UPF/5G or SPGWu/LTE components in order to:\n1. Boost them for those which does not have any fast packet processing enabled, or\n2. Co-locate them with other fast packet processing solutions (e.g. DPDK)\n\nPossible scenarios that take advantage of this type of technology: MEC, 5G NPN (Non Public Networks), on-premise, 5G enterprise, and much more.\n\n## Design\n\nThe library is divided in layers:\n- **Management Layer**: An user space layer responsible to receive requests from the third-party UPF/SPGWu components to manage PFCP sessions and BPF programs lifecycle\n- **Datapath Layer**: A kernel space layer representing by BPF/XDP programs responsible to handle the user traffic (datapath) for fast packet processing\n\nThe high level design is shown in figure below.\n\n\u003cimg src=\"img/up-ebpf-xdp-high-level.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\n\nThe library has a component, called `PFCP Session Manager`, which is a C++ API responsible for managing PFCP (Packet Forwarding Control Protocol) sessions. This layer selects the highest PDR and its rules for each PFCP session to compose the datapath Linux kernel. It is the `eBPF Program Manager`, which is responsible for loading/unloading the BPF programs. The BPF program is mapped to each rule defined in highest precedence PDR (e.g. FAR) for each PFCP session created. The fast path is composed of three main functions: Parser, Detection (both in entry BPF section) and Rule. The image below shows this in more detail.\n\n\u003cimg src=\"img/up-ebpf-xdp-high-level2.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\n- Parser: responsible to parse the GTP and UDP packets\n- Detector: responsible for matching the Packet Detection Information (TEID, source interface and UE IP address) with the header of the packet. If matches, so the rules of the PFCP session context must be applied\n- Rule: responsible to encapsulate the logic of one rule (e.g. FAR, QER, BAR, etc). Depending on the PFCP session context, it might have more than one rule available in the datapath.\n\n\u003e The FAR is mandatory according to the 3GPP specification\n\nA low-level design (Datapath Layer) is shown below.\n\n\u003cimg src=\"img/v2-bpf-pipeline-base.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\n### Activity Diagrams\n\nFigure: PFCP session creation activity diagram in Management Layer.\n\n\u003cimg src=\"img/v2-management-layer.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\nFigure: On new packet received activity diagram in Datapath Layer. There are two pipeline: one with only the FAR and the other one with QER and FAR.\n\n\u003cimg src=\"img/v2-bpf-pipeline.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\n\n## Features\n\nAs described in 3GPP TS 29.244, the Information Elements (IEs) are part of the PFCP context. The PFCP context is created by sending a PFCP Session Establishment Request message. The main features supported in this project are:\n\nManagement Layer - CRUD\n- PFCP Session\n- PDR (Packet Detection Rule)\n- FAR (Forwarding Action Rule)\n\nFast Datapath Layer\n- UDP and GTP parse\n- Traffic detection based on PDR\n- Traffic forwarding based on FAR\n\nThe 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.\n\n\u003cimg src=\"img/up-ebpf-xdp-ies.svg\" alt=\"drawing\" width=\"600\"/\u003e\n\n## :construction: Future Work\n\n- QER (QoS Enforcement Rule)\n- CO-RE for tracing.\n- PoC with OpenAirInterface\n\n## Main Dependencies\n\nCore\n- libbpf\n- bpftool\n- spdlog\n- clang \u003e= version 3.4.0\n- llvm \u003e= version 3.7.1\n- kernel-headers =\u003e version 5.4\n- cmake \u003e= 3.16\n\nTest\n- trex v2.86\n- sysstat (mpstat)\n- ethtool\n- gtest\n\n## First Steps\n\nFirst of all, make sure you have installed [git-lfs](https://git-lfs.github.com/). The LFS repository is used to store the `bpftool` binary.\n\nAfter downloaded and installed it, clone this repository:\n\n```\ngit clone https://github.com/navarrothiago/upf-bpf.git\n```\n\nAfter cloning the repository, configure your [env.sh](env.sh) file (on the repository root folder) to match your dev or test environment, using the [.env.sample.sh](.env.sample.sh) file as a template\n\nThe project uses a docker container to build the UPF library. The command below will provision the docker image with all the project dependencies.\n\n\u003e :memo: You'll need the Docker Container Runtime package and the Docker Compose utility to set up the dev or test environment\n\n```\nmake docker-build\n```\n\nAfter that, run the container with:\n\n```\nmake docker-run\n```\n\n\u003e You can also use the vscode development container feature to build the image and login into the container.\n\u003e Check [here](https://code.visualstudio.com/docs/remote/create-dev-container#_create-a-devcontainerjson-file) to understand how to open the [devcontainer.json](.devcontainer/devcontainer.json) file.\n\nInside the container, compile the dependencies with\n\n```\nmake setup\n```\n\n## Build and Installation\n\nThe library is built and installed with\n\n```\nmake install\n```\n\nThe `package` folder is created with the headers, library and some binaries for testing.\n\n```\npackage\n├── bin       # Contains binaries for testing\n├── include   # Contains headers\n├── lib       # Contains libupf_xdp.a library\n└── tests     # Contains scripts for testing\n```\n\n## How to Test\n\nThe test is based on RFC2544-like measurements. The testbed is composed of two servers: Trex Traffic Generator and HTTP API + upf-bpf.\n\nRequirements:\n\n- Both machines with Ubuntu 20.04.02 LTS installed with Linux kernel v5.4.0-72-generic. One machine is used to generate user traffic with TRex Traffic Generator and the other is the DUT (Device Under Test) where the upf-bpf is deployed.\n- Both machine contains two NICs\n  - For the Trex traffic generator, both NICs drivers must support DPDK. Check out the [Table 5 - Supported NICs](https://trex-tgn.cisco.com/trex/doc/trex_manual.html#_download_and_installation)\n  - For DUT, both NICs drivers must support XDP. Check out [here](https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md#xdp).\n\n\nTest environment:\n\n\u003cimg src=\"img/setup-performance-evaluation.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\nNetwork topology:\n\n\u003cimg src=\"img/network.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\n### Setup Trex Traffic Generator Server\n\nThis machine must have installed the Trex traffic generator. You can check the [trex manual](https://trex-tgn.cisco.com/trex/doc/trex_manual.html) or you can based on the scripts that are called when `make trex` is executed (unstable).\n\n### Setup HTTP API + upf-bpf Server\n\nAfter running `make install` inside the docker container, copy the application `./package/bin/api` to the DUT machine. **Your host must have kernel \u003e= v5.4**.\n\nSteps:\n1. Run Trex Traffic Generator\n1. Run HTTP API + upf-bpf\n1. Configure interfaces (/configure)\n1. Create PFCP Session context (/createSession)\n1. Configure the number of Rx queue in DUT\n1. Generate the GTP/UDP flows (pkt size = 64B)\n1. Collects metrics (CPU load, packet loss, throughput)\n\nFor step 1, see the [trex manual](https://trex-tgn.cisco.com/trex/doc/trex_manual.html)\n\nFor step 2, run HTTP API + upf-bpf with:\n```\nsudo ./bin/api 10.1.1.27 80\n```\n\nFor steps 3 and 4, there are Postman files are available: [Uplink](tests/api/requests_body/gtp-postman-colletion.json) and [Downlink](tests/api/requests_body/udp-postman-colletion.json). Check the JSON message for each step.\n\nFor steps 5, 6 and 7, it was implemented a Python [script](https://github.com/navarrothiago/upf-bpf/blob/c1250469a101a10c4b7ac38503a6edda6c5ca1f1/tests/trex/test_cases/run.py) to automate the process. The script executes the test case varying the number of the rx queue. In the end, a report is generated based on JSON format with all the metrics (i.e throughput and CPU load) for each execution. The flows leverage the [Trex Field Engine](https://trex-tgn.cisco.com/trex/doc/cp_stl_docs/api/field_engine.html) to generate the flows. You can also generate the flow manually in the Trex Traffic Generator server.\n\nIn order to execute the script, run the following command inside the docker container:\n```\nexport PYTHONPATH='/workspaces/tests/trex/trex_client/interactive/'\n\n# example to generate GTP flow with 12mpps of throughput.\n./tests/trex/test_cases/run.py -m 12mpps -p \u003cpassword_trex_server\u003e -f gtp\n# example to generate UDP flow with 100% of throughput.\n./tests/trex/test_cases/run.py -m 100% -p \u003cpassword_trex_server\u003e -f udp\n```\n\n\u003e :memo: The `env.sh` file must be configured properly in order to have a successful execution.\n\nThere is a tmux session script available [here](tests/scripts/start_session) that were developed to a specific scenario. Some parameters are hardcoded. Feel free to change according to your needs. If you need any help, open an issue or contact me. PR are welcome!!\n\n\u003cimg src=\"img/tmux-upf.png\" alt=\"drawing\" width=\"700\"/\u003e\n\n\u003e :warning: Some scripts were developed to work in one environment. As you can see in [.env.sample.sh](.env.sample.sh), there are variables to configure the jump server, trex version, GTP and UDP interfaces (downlink and uplink), etc. **You might face some problems when trying to execute some of them, because they were not exhaustive tests in other environments.**\n\n### UTs\n\nSome UTs were developed for the Session Management layer. You can execute inside the container:\n\n```\nmake config-veth-pair\nmake build-tests\nmake run-session-manager-tests\n```\nIf you face any problem, feel free to open an issue or contact me.\n\n## :rocket: Benchmark\n\nSetup: Intel(R) Xeon(R) CPU E5-2620 v2 @ 2.10GHz, 32GiB of the DRAM, 15M of L3 cache, 6 cores (hyper-threading disabled), dual-port 82599ES 10-Gigabit SFI/SFP+ NIC. Both machines have Ubuntu 20.04.02 LTS installed with Linux kernel v5.4.0-72-generic.\n\n\u003e Disable the hyper-threading with `echo off \u003e /sys/devices/system/cpu/smt/control`\n\n**Downlink** | **Uplink**\n---|---\n\u003cimg src=\"tests/reports/img/Downlink Max Throughput.svg\" alt=\"drawing\" width=\"500\"/\u003e| \u003cimg src=\"tests/reports/img/Uplink Max Throughput.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\u003cimg src=\"tests/reports/img/Downlink Max ThroughputLoad per Core - 6 Rx Queue.svg\" alt=\"drawing\" width=\"500\"/\u003e| \u003cimg src=\"tests/reports/img/Uplink Max ThroughputLoad per Core - 6 Rx Queue.svg\" alt=\"drawing\" width=\"500\"/\u003e\n\nCheck the [Jupyter notebook](notebook.ipynb) to see how the graphics are generated.\n\n\u003e :memo: For more graphics, check [this](tests/reports/img) folder.\n\nTime spent to inject BPF program into the kernel after receive the PFCP Establishement Request message.\n\n**Version**| **BPF section** | **BPF Insn** | **Injection (ms)**\n--|--|--|--\nv1.0.0|PFCP Session|402|27\nv2.0.0|FAR|272|1\n\n\u003e :memo: The main reason is due the logic related to lookup the PDR is implemented in the control plane (Management Layer) in v2.0.0 and in the data plane in v1.0.0. The PFCP session was composed with only one FAR.\n\n### Jupyter Notebook\n\nThe data collected for uplink (GTP decapsulation) and downlink (GTP encapsulation) e2e testing are available:\n\n- [Uplink - GTP Decapsulation Report](tests/reports/v2.0.0/UplinkMaxThoughtput.json)\n- [Downlink - GTP Encapsulation Report](tests/reports/v2.0.0/DownlinkMaxThoughtput.json)\n\n Firstly, you need to install the python dependencies:\n\n```\n# create our virtual environment\npython3 -m venv env\n# activate our virtual environment\nsource env/bin/activate\n# install dependencies\npip3 install -r requirements.txt\n```\n\nNow, you can execute [notebook](notebook.ipynb) using Jupyter.\n\n## Tree\n\n```\n├── build: Generated build directory.\n├── cmake: Cmake files configuration directory\n├── extern: Submodule repositories\n├── include: Include files\n├── samples: Samples like XDP BPF hello world\n├── src: Source files directory\n├── tests: UTs, HTTP API srcs, scripts for testing, trex installation\n├── Makefile: Encapsulate cmake calls for build, run samples, clean, etc\n└── README.md: Readme file\n```\n\n## Trex Traffic Generator\n\nIf you faced `FileNotFoundError: [Errno 2] No such file or directory: b'liblibc.a'` when executing trex, for instance:\n```\n cd tests/scripts/../trex/v2.87; sudo ./trex-console --port 1235 --async_port 1236\n```\nCreate a symbolic from `libc.a -\u003e liblibc.a` (Manjaro)\n\n```\nsudo ln -s -f /usr/lib64/libc.a /usr/lib64/liblibc.a\n```\n\n\n## Contribute\n\nIf you think this could be better, **please open an issue or start a discussion**.\n\nPRs ARE WELCOME :+1:\n\n## :star: BibTeX\n\nThe paper is available [here](docs/Paper___An_In_Kernel_Solution_Based_on_XDP__Design__Prototype_and_Performance_Evaluation.pdf).\n\n```bibtex\n@INPROCEEDINGS{Amar2110:Kernel,\nAUTHOR=\"Thiago Arruda Navarro do Amaral and Raphael {Vicente Rosa} and David Moura\nand Christian {Esteve Rothenberg}\",\nTITLE=\"An {In-Kernel} Solution Based on {XDP} for {5G} {UPF:} Design, Prototype\nand Performance Evaluation\",\nBOOKTITLE=\"2021 1st Joint International Workshop on Network Programmability and\nAutomation (NetPA 2021)\",\nADDRESS=\"Izmir, Turkey, Turkey\",\nDAYS=24,\nMONTH=oct,\nYEAR=2021,\nKEYWORDS=\"5G; XDP; UPF\",\nABSTRACT=\"The edge computing infrastructure can scale from datacenters to single\ndevice. The well-known technology for fast packet processing is DPDK, which\nhas outstanding performance regarding the throughput and latency. However,\nthere are some drawbacks when the usage is done in the edge: (i) the\npolling mechanism for packet processing keeps the CPU exclusively occupied\neven if there is no traffic, leading to wasted resources; and (ii) DPDK\ninterface becomes unavailable for the applications inside the host, so the\nintegration between a non-DPDK application and a DPDK application becomes a\nhard task. In this paper, we propose an open-source in-kernel 5G UPF\nsolution based on 3GPP Release 16 to be deployed in a restrictive\nenvironment like MEC, where MEC host and UPF are collocated with the Base\nStation, sharing the same computational and network resources. The solution\nleverages the eBPF/XDP, a novel Linux kernel technology for fast packet\nprocessing. We show it can scale and achieve 10 Mpps using only 60\\% of the\nCPU with 6 cores.\"\n}\n```\n\n## :notebook: Contacts\n\n- [Discord Server](https://discord.gg/TtdUvnA4nq)\n- Mail: \u003cnavarro (dot) ime (at) gmail [dot] com\u003e\n- Twitter: [@navarr0thiag0](https://twitter.com/navarr0thiag0)\n\n## :information_source: References\n\n- [Paper - Run-time Adaptive In-Kernel BPF/XDP Solution for 5G UPF](docs/Paper___Run-time_Adaptive_In-Kernel_BPF_XDP_Solution_for_5G_UPF.pdf)\n- [Paper - An In-Kernel Solution Based on XDP for 5G UPF: Design, Prototype and Performance Evaluation](docs/Paper___An_In_Kernel_Solution_Based_on_XDP__Design__Prototype_and_Performance_Evaluation.pdf)\n- [Video - Project Overview](https://youtu.be/Av_k_fZKCfM)\n- [Slides - Project Overview](https://docs.google.com/presentation/d/1osOheCFV3c3wn4hDbo5R3coL8nDeaxjVb7D33QT41jw/edit?usp=sharing)\n- [Video - Performance Evaluation with UPF eBPF/XDP Library for 5G Core Network](https://www.youtube.com/watch?v=6KYFDMJJH2o)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavarrothiago%2Fupf-bpf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavarrothiago%2Fupf-bpf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavarrothiago%2Fupf-bpf/lists"}