Home

Awesome

eUPF

<div align="center">

GitHub Release Build Test Security License: Apache-2.0

</div>

eUPF 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.

The eUPF has been tested with three different 5G cores: Free5GC, Open5GS and OpenAirInterface. The OpenAirInterface gNB was also used during testing.

What is 5G core and CUPS

5G core uses network virtualized functions (NVF) to provide connectivity and services. Control and user plane separation (CUPS) is important architecture enhancement that separates control plane and user plane inside 5G core. User 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.

image

Quick start guide

Super fast & simple way is to download and run our docker image. It will start standalone eUPF with the default configuration:

sudo docker run -d --rm --privileged \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -p 8080 -p 9090 --name your-eupf-def \
   ghcr.io/edgecomllc/eupf:main

Notes

<details><summary><i>See startup parameters you might want to change</i></summary> <p> </p> </details> </p>

In 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:

sudo docker run -d --rm -v --privileged \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -p 8081 -p 9091 --name your-eupf-custom \
  -e UPF_INTERFACE_NAME=[eth0,n6] -e UPF_XDP_ATTACH_MODE=generic \
  -e UPF_API_ADDRESS=:8081 -e UPF_PFCP_ADDRESS=:8806 \
  -e UPF_METRICS_ADDRESS=:9091 -e UPF_PFCP_NODE_ID=10.100.50.241 \
  -e UPF_N3_ADDRESS=10.100.50.233 \
  ghcr.io/edgecomllc/eupf:main

What's next?

Read eUPF configuration guide for more info about how to configure eUPF.

To go further, see the eUPF installation guide to learn how to run eUPF in different environments with different 5G core implementations using docker-compose or Kubernetes cluster.

For statistics you can gather, see the eUPF metrics and monitoring guide.

You can find different types of implementation in the Implementation examples.

Implementation notes

eUPF 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.

The eUPF control plane is an userspace application which receives packet processing rules from SMF and configures forwarding plane for proper forwarding.

The 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.

eUPF 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).

Brief functional description

FAR support

eUPF supports FAR rules in PDR. Only one FAR rule per PDR is supported.

QER support

eUPF supports QER rules in PDR. Currently only one QER rule per PDR is supported.

SDF filters support

eUPF is able to apply SDF filters in PDR. Currently only one SDF filter per GTP tunnel is supported.

GTP path management

eUPF supports sending GTP Echo requests towards neighbour GTP nodes. Every neighbour GTP node should be explicitly configured. See gtp_peer configuration parameter.

Architecture

<details><summary>Show me</summary>

Eagle-eye overview

UPF-Arch2

Detailed architecture

image

</details>

Roadmap

<details><summary>Show me</summary>

Control plane

Data plane

Management plane

3GPP specs compatibility

</details>

Running from sources

Prerequisites

On Ubuntu 22.04, you can install these using the following commands:

Basic dependencies

sudo apt install wget git clang llvm gcc-multilib libbpf-dev

Golang 1.20.3

ℹ Please skip this step if you have golang 1.20.3 already installed.

sudo rm -rf /usr/local/go
wget https://go.dev/dl/go1.20.3.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.3.linux-amd64.tar.gz
export PATH="/usr/local/go/bin:${PATH}"

Manual build

Step 1: Install the Swag command line tool for Golang

This is used to automatically generate RESTful API documentation.

go install github.com/swaggo/swag/cmd/swag@v1.8.12

Step 2: Clone the eUPF repository and change to the directory

git clone https://github.com/edgecomllc/eupf.git
cd eupf

Step 3: Run the code generators

go generate -v ./cmd/...

Sometimes during this step you may see errors like:

running "swag": exec: "swag": executable file not found in $PATH

Make sure that swag was successfuly installed(step 1) and path to swag binary is in the PATH environment variable.

Usually GO Path is supposed to already be on the PATH environment variable. Use export PATH=$(go env GOPATH)/bin:$PATH otherwise and repeat current step again.

Step 4: Build eUPF

go build -v -o bin/eupf ./cmd/

Step 5: Run the application

Run binary with privileges allowing to increase memory-ulimits

sudo ./bin/eupf

This 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.

Build docker image

Use this command to build eupf's docker image: docker build -t local/eupf:latest .

You 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 .

Hardware requirements

Contribution

Please create an issue to report a bug or share an idea.

Translated docs

Please check this link to find translated docs.

License

This project is licensed under the Apache-2.0 Creative Commons License - see the LICENSE file for details