{"id":15282544,"url":"https://github.com/edgecomllc/eupf","last_synced_at":"2025-04-14T13:11:20.330Z","repository":{"id":173039424,"uuid":"573107149","full_name":"edgecomllc/eupf","owner":"edgecomllc","description":"5G User Plane Function (UPF) based on eBPF","archived":false,"fork":false,"pushed_at":"2025-04-13T20:39:20.000Z","size":1900,"stargazers_count":132,"open_issues_count":27,"forks_count":25,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-13T21:31:01.605Z","etag":null,"topics":["3gpp","5g","cilium","ebpf","upf"],"latest_commit_sha":null,"homepage":"","language":"Go","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/edgecomllc.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":"2022-12-01T18:01:16.000Z","updated_at":"2025-04-13T03:50:21.000Z","dependencies_parsed_at":"2023-12-28T08:30:38.685Z","dependency_job_id":"7794c241-04e8-407c-9832-63000d176c2f","html_url":"https://github.com/edgecomllc/eupf","commit_stats":null,"previous_names":["edgecomllc/eupf"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgecomllc%2Feupf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgecomllc%2Feupf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgecomllc%2Feupf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgecomllc%2Feupf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edgecomllc","download_url":"https://codeload.github.com/edgecomllc/eupf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248886325,"owners_count":21177643,"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","cilium","ebpf","upf"],"created_at":"2024-09-30T14:26:47.647Z","updated_at":"2025-04-14T13:11:19.223Z","avatar_url":"https://github.com/edgecomllc.png","language":"Go","funding_links":[],"categories":["Core"],"sub_categories":["5G"],"readme":"# eUPF\n\n\u003cdiv align=\"center\"\u003e\n\n[![GitHub Release][release-img]][release]\n[![Build][build-img]][build]\n[![Test][test-img]][test]\n[![Security][security-test-img]][security-test]\n[![License: Apache-2.0][license-img]][license]\n\n\u003c/div\u003e\n\neUPF is the opensource User Plane Function (UPF) project for using inside or \"outside\" of any 3GPP 5G core. The goal of the project is to provide high-observability and easily-deployed software for a various cases like multi-access edge computing (MEC) and local traffic breakout. eUPF is built with eBPF to provide high observability and performance.\n\n The eUPF has been tested with three different 5G cores: Free5GC, Open5GS and OpenAirInterface. The OpenAirInterface gNB was also used during testing.\n\n## What is 5G core and CUPS\n\n5G core uses network virtualized functions (NVF) to provide connectivity and services.\nControl and user plane separation (CUPS) is important architecture enhancement that separates control plane and user plane inside 5G core.\nUser plane function (UPF) is the \"decapsulating and routing\" function that extracts user plane traffic from GPRS tunneling protocol (GTP) and route it to the public data network or local network via the best available path.\n\n![image](docs/pictures/eupf.png)\n\n## Quick start guide\n\nSuper fast \u0026 simple way is to download and run our docker image. It will start standalone eUPF with the default configuration:\n```bash\nsudo docker run -d --rm --privileged \\\n  -v /sys/fs/bpf:/sys/fs/bpf \\\n  -v /sys/kernel/debug:/sys/kernel/debug:ro \\\n  -p 8080 -p 9090 --name your-eupf-def \\\n   ghcr.io/edgecomllc/eupf:main\n```\n### Notes\n- 📝 *Linux Kernel **5.15.0-25-generic** is the minimum release version it has been tested on. Previous versions are not supported.*\n- ℹ The eBPF filesystem must be mounted in the host filesystem allowing the eUPF to persist eBPF resources across restarts so that the datapath can continue to operate while the eUPF is subsequently restarted or upgraded.\nUse following command to mount it: `sudo mount bpffs /sys/fs/bpf -t bpf`\n- ℹ In order to perform low-level operations like loading ebpf objects some additional privileges are required(NET_ADMIN \u0026 SYS_ADMIN)\n- ℹ During startup eupf sets rlimits, so corresponding priviledges are required (ulimit)\n\n\u003cdetails\u003e\u003csummary\u003e\u003ci\u003eSee startup parameters you might want to change\u003c/i\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n   - UPF_INTERFACE_NAME=lo    *Network interfaces handling N3 (GTP) \u0026 N6 (SGi) traffic.*\n   - UPF_N3_ADDRESS=127.0.0.1 *IPv4 address for N3 interface*\n   - UPF_N9_ADDRESS=127.0.0.1 *IPv4 address for N9 interface*\n   - UPF_XDP_ATTACH_MODE=generic *XDP attach mode. Generic-only at the moment*\n   - UPF_API_ADDRESS=:8080    *Local host:port for serving [REST API](api.md) server*\n   - UPF_PFCP_ADDRESS=:8805   *Local host:port that PFCP server will listen to*\n   - UPF_PFCP_NODE_ID=127.0.0.1  *Local NodeID for PFCP protocol. Format is IPv4 address*\n   - UPF_METRICS_ADDRESS=:9090   *Local host:port for serving Prometheus mertrics endpoint*\n\u003c/p\u003e\n\u003c/details\u003e\n\u003c/p\u003e\n\nIn a real-world scenario, you would likely need to replace the interface names and IP addresses with values that are applicable to your environment. You can do so with the `-e` option, for example:\n\n```bash\nsudo docker run -d --rm -v --privileged \\\n  -v /sys/fs/bpf:/sys/fs/bpf \\\n  -v /sys/kernel/debug:/sys/kernel/debug:ro \\\n  -p 8081 -p 9091 --name your-eupf-custom \\\n  -e UPF_INTERFACE_NAME=[eth0,n6] -e UPF_XDP_ATTACH_MODE=generic \\\n  -e UPF_API_ADDRESS=:8081 -e UPF_PFCP_ADDRESS=:8806 \\\n  -e UPF_METRICS_ADDRESS=:9091 -e UPF_PFCP_NODE_ID=10.100.50.241 \\\n  -e UPF_N3_ADDRESS=10.100.50.233 \\\n  ghcr.io/edgecomllc/eupf:main\n```\n\n## What's next?\nRead **[eUPF configuration guide](./docs/Configuration.md)** for more info about how to configure eUPF.\n\nTo go further, see the **[eUPF installation guide](./docs/install.md)** to learn how to run eUPF in different environments with different 5G core implementations using docker-compose or Kubernetes cluster.\n\nFor statistics you can gather, see the **[eUPF metrics and monitoring guide](./docs/metrics.md)**.\n\nYou can find different types of implementation in the **[Implementation examples](./docs/implementation_examples.md)**.\n\n## Implementation notes\n\neUPF as a part of 5G mobile core network implements data network gateway function. It communicates with SMF via PFCP protocol (N4 interface) and forwards packets between core and data networks(N3 and N6 interfaces correspondingly). These two main UPF parts are implemented in two separate components: control plane and forwarding plane.\n\nThe eUPF control plane is an userspace application which receives packet processing rules from SMF and configures forwarding plane for proper forwarding.\n\nThe eUPF forwarding plane is based on eBPF packet processing. When started eUPF adds eBPF XDP hook program in order to process network packets as close to NIC as possible. eBPF program consists of several pipeline steps: determine PDR, apply gating, qos and forwarding rules.\n\neUPF relies on kernel routing when making routing decision for incoming network packets. When it is not possible to determine packet route via kernel FIB lookup, eUPF passes such packet to kernel as a fallback path. This approach obviously affects performance but allows maintaining correct kernel routing process (ex., filling arp tables).\n\n### Brief functional description\n\n#### FAR support\n\neUPF supports FAR rules in PDR. Only one FAR rule per PDR is supported.\n\n#### QER support\n\neUPF supports QER rules in PDR. Currently only one QER rule per PDR is supported.\n\n#### SDF filters support\n\neUPF is able to apply SDF filters in PDR. Currently only one SDF filter per GTP tunnel is supported.\n\n#### GTP path management\n\neUPF supports sending GTP Echo requests towards neighbour GTP nodes. Every neighbour GTP node should be explicitly configured. [See](docs/Configuration.md) `gtp_peer` configuration parameter.\n\n### Architecture\n\n\u003cdetails\u003e\u003csummary\u003eShow me\u003c/summary\u003e\n\n#### Eagle-eye overview\n\n![UPF-Arch2](https://user-images.githubusercontent.com/20152142/207142700-cc3f17a5-203f-4b43-b712-a518cb627968.png)\n\n#### Detailed architecture\n![image](docs/pictures/eupf-arch.png)\n\n\u003c/details\u003e\n\n### Roadmap\n\n\u003cdetails\u003e\u003csummary\u003eShow me\u003c/summary\u003e\n\n#### Control plane\n\n- [x]  PFCP Association Setup/Release and Heartbeats\n- [x]  Session Establishment/Modification with support for PFCP entities such as Packet Detection Rules (PDRs), Forwarding Action Rules (FARs), QoS Enforcement Rules (QERs).\n- [ ]  UPF-initiated PFCP association\n- [x]  UPF-based UE IP address assignment\n\n#### Data plane\n\n- [x]  IPv4 support\n- [x]  N3, N4, N6 interfaces\n- [x]  Single \u0026 Multi-port support\n- [x]  Static IP routing\n- [x]  Basic QoS support with per-session rate limiting\n- [x]  I-UPF/A-UPF ULCL/Branching (N9 interface)\n\n#### Management plane\n- [x]  Free5gc compatibility\n- [x]  Open5gs compatibility\n- [x]  Integration with Prometheus for exporting PFCP and data plane-level metrics\n- [ ]  Monitoring/Debugging capabilities using tcpdump and cli\n\n#### 3GPP specs compatibility\n- [x]  `FTUP` F-TEID allocation / release in the UP function is supported by the UP function.\n- [x]  `UEIP` Allocating UE IP addresses or prefixes.\n- [ ]  `SSET` PFCP sessions successively controlled by different SMFs of a same SMF Set.\n- [ ]  `MPAS` Multiple PFCP associations to the SMFs in an SMF set.\n- [ ]  `QFQM` Per QoS flow per UE QoS monitoring.\n- [ ]  `GPQM` Per GTP-U Path QoS monitoring.\n- [ ]  `RTTWP` RTT measurements towards the UE Without PMF.\n\n \u003c/details\u003e\n\n## Running from sources\n\n### Prerequisites\n\n-\tUbuntu 22.04 LTS or higher\n-\tGit 2.34\n-\tGolang 1.20.3\n-\tClang 14.0.0\n-\tLLVM 14.0\n-\tGcc 11.4.0\n-\tlibbpf-dev 0.5.0\n-\tSwag 1.8.12\n-\tLinux Kernel 5.15.0-25\n\n**On Ubuntu 22.04**, you can install these using the following commands:\n\n#### Basic dependencies\n```bash\nsudo apt install wget git clang llvm gcc-multilib libbpf-dev\n```\n#### Golang 1.20.3\nℹ Please skip this step if you have golang 1.20.3 already installed.\n\n```bash\nsudo rm -rf /usr/local/go\nwget https://go.dev/dl/go1.20.3.linux-amd64.tar.gz\nsudo tar -C /usr/local -xzf go1.20.3.linux-amd64.tar.gz\nexport PATH=\"/usr/local/go/bin:${PATH}\"\n```\n\n### Manual build\n\n#### Step 1: Install the Swag command line tool for Golang\nThis is used to automatically generate RESTful API documentation.\n\n```bash\ngo install github.com/swaggo/swag/cmd/swag@v1.8.12\n```\n\n#### Step 2: Clone the eUPF repository and change to the directory\n\n```bash\ngit clone https://github.com/edgecomllc/eupf.git\ncd eupf\n```\n\n#### Step 3: Run the code generators\n\n```bash\ngo generate -v ./cmd/...\n```\n\nSometimes during this step you may see errors like:\n```\nrunning \"swag\": exec: \"swag\": executable file not found in $PATH\n```\n\nMake sure that `swag` was successfuly installed(step 1) and path to swag binary is in the PATH environment variable.\n\nUsually GO Path is supposed to already be on the PATH environment variable.\nUse `export PATH=$(go env GOPATH)/bin:$PATH` otherwise and repeat current step again.\n\n\n#### Step 4: Build eUPF\n\n```bash\ngo build -v -o bin/eupf ./cmd/\n```\n#### Step 5: Run the application\n\nRun binary with privileges allowing to increase [memory-ulimits](https://prototype-kernel.readthedocs.io/en/latest/bpf/troubleshooting.html#memory-ulimits)\n\n```bash\nsudo ./bin/eupf\n```\n\nThis should start application with the default configuration. Please adjust the contents of the configuration file and the command-line arguments as needed for your application and environment.\n\n### Build docker image\n\nUse this command to build eupf's docker image: `docker build -t local/eupf:latest .`\n\nYou can also define several build arguments to configure eUPF image: `docker build -t local/eupf:latest --build-arg BPF_ENABLE_LOG=1 --build-arg BPF_ENABLE_ROUTE_CACHE=1 .`\n\n### Hardware requirements\n\n- CPU: any popular CPU is supported, incl. x86, x86_64, x86, ppc64le, armhf, armv7, aarch64, ppc64le, s390x\n- CPU_cores: 1 core is enough to run eUPF\n- RAM: you need up to 70MB to run eUPF and up to 512MB to run Linux kernel\n- HDD: 50MB of free space is required to install eUPF. Different types of storage can be used: HDD, SSD, SD-card, USB-stick\n- NIC: Any internal or external networking interface that can be used in Linux\n\n## Contribution\n\nPlease create an issue to report a bug or share an idea. See our [Contributing Guide](./CONTRIBUTING.md) for details.\n\n## License\nThis project is licensed under the [Apache-2.0 Creative Commons License](https://www.apache.org/licenses/LICENSE-2.0) - see the [LICENSE file](./LICENSE) for details\n\n---\n\n[release]: https://github.com/edgecomllc/eupf/releases\n[release-img]: https://img.shields.io/github/release/edgecomllc/eupf.svg?logo=github\n[build]: https://github.com/edgecomllc/eupf/actions/workflows/build.yml\n[build-img]: https://github.com/edgecomllc/eupf/actions/workflows/build.yml/badge.svg\n[test]: https://github.com/edgecomllc/eupf/actions/workflows/test.yml\n[test-img]: https://github.com/edgecomllc/eupf/actions/workflows/test.yml/badge.svg\n[security-test]: https://github.com/edgecomllc/eupf/actions/workflows/trivy.yml\n[security-test-img]: https://github.com/edgecomllc/eupf/actions/workflows/trivy.yml/badge.svg\n[license]: https://github.com/edgecomllc/eupf/blob/main/LICENSE\n[license-img]: https://img.shields.io/badge/License-Apache%202.0-blue.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgecomllc%2Feupf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedgecomllc%2Feupf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgecomllc%2Feupf/lists"}