[#39] Cleans up environment

.env.sample.sh

@@ -0,0 +1,94 @@
+# Docker container workspace.
+WORKSPACE=/workspaces
+
+BPF_SAMPLES_DIR="${WORKSPACE}"/build/samples
+BPF_BINARY_DIR="${WORKSPACE}"/build/tests
+
+# Compilation environment variable.
+NUM_THREADS=
+
+# Docker environment variable.
+USERNAME=oai-spgwu
+IMAGE_TAG=upee
+IMAGE_VERSION=v1.0
+DOCKERFILE=Dockerfile
+SSH_FOLDER=~/.ssh
+SSH_PUBLIC_KEY_FILE=id_rsa.pub
+SSH_PRIVATE_KEY_FILE=id_rsa
+SSH_CONFIG_FILE=config
+GIT_CONFIG=~/.gitconfig
+BASH_RC=~/.bashrc
+
+# TODO navarrothiago - Remove hardcoded https://github.com/navarrothiago/upf-bpf/issues/24
+DEVICE_IN=
+DEVICE_OUT_UL=
+DEVICE_OUT_DL=
+
+# TODO navarrothiago - pass as exec param.
+GTP_INTERFACE=
+UDP_INTERFACE=
+SOCKET_BUFFER_ENABLED=0
+
+# Test environment variables.
+TEST_CASE=hello_world
+GTEST_FILTER_ARGS="*.*"
+
+# Jump server.
+JUMP_SERVER_NAME=
+JUMP_SERVER_USERNAME=
+JUMP_SERVER_IP=
+JUMP_SERVER_PORT=
+
+# Trex version.
+TREX_VERSION=v2.87
+TREX_SHA256SUM=290c1be468335a2de2e69f217b139c9b1198732e529bfd069348d05297548b8a
+
+# Trex server configuration.
+TREX_SERVER_NAME= # Warning: Optional - If you set the name, it must be configured on your ssh config.
+TREX_SERVER_IP=
+TREX_SERVER_ASYNC_PORT=
+TREX_SERVER_SYNC_PORT=
+TREX_SERVER_USERNAME=
+TREX_SERVER_SSH="${TREX_SERVER_NAME}"
+# TREX_SERVER_SSH="${TREX_SERVER_USERNAME}"@"${TREX_SERVER_IP}"
+TREX_SERVER_UPLOAD_DIR=
+TREX_SERVER_DIR="${TREX_SERVER_UPLOAD_DIR}"/"${TREX_VERSION}"
+
+# Trex client configuration.
+TREX_CLIENT_NAME= # Warning: Optional - If you set the name, it must be configured on your ssh config.
+TREX_CLIENT_IP=
+TREX_CLIENT_USERNAME=
+TREX_CLIENT_SSH="${TREX_CLIENT_NAME}"
+# TREX_CLIENT_SSH="${TREX_CLIENT_USERNAME}"@"${TREX_CLIENT_IP}"
+TREX_CLIENT_UPLOAD_DIR=
+TREX_CLIENT_DIR="${TREX_CLIENT_UPLOAD_DIR}"/trex_client
+TREX_CLIENT_LIB_DIR="${TREX_CLIENT_DIR}"/interactive
+
+# DUT - Device Under Test Configuration.
+DUT_NAME= # Warning: Optional - If you set the name, it must be configured on your ssh config.
+DUT_IP=
+DUT_USERNAME=
+DUT_UPLOAD_DIR=
+
+# Test local configuration.
+LOCAL_CONFIG_DIR="${WORKSPACE}"/tests/trex/config
+LOCAL_TRAFFIC_DIR="${WORKSPACE}"/tests/trex/traffic
+LOCAL_TEST_CASES_DIR="${WORKSPACE}"/tests/trex/test_cases
+LOCAL_SERVER_UPLOAD_DIR="${WORKSPACE}"/tests/trex
+LOCAL_PACKAGE="${WORKSPACE}"/package
+
+# Test remote configuration
+REMOTE_CONFIG_DIR="${TREX_SERVER_UPLOAD_DIR}"/config
+REMOTE_TRAFFIC_DIR="${TREX_SERVER_UPLOAD_DIR}"/traffic
+REMOTE_TEST_CASES_DIR="${TREX_SERVER_UPLOAD_DIR}"/test_cases
+
+# SSH port forwarding configuration
+LOCAL_HTTP_SSH_PORT_FORWARDING=
+LOCAL_TREX_SYNC_SSH_PORT_FORWARDING=
+LOCAL_TREX_ASYNC_SSH_PORT_FORWARDING=
+API_HTTP_PORT=
+
+# Programs name
+API_PROGRAM_NAME=api
+
+PYTHONPATH=/workspaces/tests/trex/trex_client/interactive/

.gitattributes

@@ -1 +1,3 @@
 bin/bpftool filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+

.gitignore

@@ -7,3 +7,4 @@ tests/trex/v*
 tests/trex/trex_client
 tests/reports/*.json
 *.png
+env.sh

CMakeLists.txt

@@ -71,8 +71,8 @@ write_basic_package_version_file(
     "${version_config}" COMPATIBILITY SameMajorVersion
 )
 
-# set(INCLUDE_INSTALL_DIR include/)
-# set(LIB_INSTALL_DIR lib/ )
+set(INCLUDE_INSTALL_DIR include/)
+set(LIB_INSTALL_DIR lib/ )
 # Configure '<PROJECT-NAME>Config.cmake'
 # Use variables:
 #   * TARGETS_EXPORT_NAME

Makefile

@@ -85,16 +85,16 @@ run-redirect-map-sample: all ## Build all and run BPF XDP redirect sample
 run-control-plane-tests: force-xdp-deload ## Run ControlPlaneTests
 	./tests/scripts/run_test ControlPlaneTests
 
-run-session-manager-tests: force-xdp-deload ## Run SessionManagerTests
-	sudo bash ./tests/scripts/run_test UPFProgramTests
+run-session-manager-tests: force-xdp-deload ## Run SessionManagerTests	
+	sudo -E bash ./tests/scripts/run_test UPFProgramTests
 
 rerun: force-xdp-deload run ## Build all and run BPF XDP UPF
 
 dut-run: ## Run ControlPlaneTests on DUT
 	sudo ./bin/ControlPlaneTests
 
 force-xdp-deload: ## Kill all and force deload XDP programs
-	sudo bash tests/scripts/force_xdp_deload
+	sudo -E bash tests/scripts/force_xdp_deload
 
 trex: ## Install, deploy configuration and run t-rex on remote server
 	tests/scripts/install_trex_remote
@@ -114,6 +114,9 @@ tmux: ## Create a test session using tmux
 docker-build: ## Build development image
 	docker/build_docker
 
+docker-build-ubuntu-18.04: ## Build development image
+	docker/build_docker ubuntu:18.04
+
 docker-run: ## Run development container
 	docker/run_docker
 

README.md

@@ -1,54 +1,133 @@
-User plane function using BPF and XDP for mobile core network (4G/5G).
+# 5G UPF using eBPF/XDP
 
-## Usage
-### Build Docker Image
+An open source C++ library powered by eBPF/XDP for user plane in mobile core network (5G/LTE).
 
-Copy the keys to jump server and run `make docker-build`
-### Testing
+The key pillars of this project are:
 
-![setup-for-GPDU-debug-issue-2-upf-bpf](https://user-images.githubusercontent.com/42647168/86470179-4486cc80-bd11-11ea-8f55-fee848b12e11.png)
+- In-kernel fast packet processing
+- Flexible and programmable dataplane
+- Portable to different systems
 
-- Open terminal in `Linux #0`
-- Configure veth pairs with `make config-veth-pair` in `Linux #0`
-- Install the spdlog library with `make setup`
-- Build, load and run program with `make run` in `Linux #0`
-- Login remote Scapy `ssh -X [email protected] "cd /work/mestrado/scapy/; sudo -S ./run_scapy"`
-- Generate GTP G-PDU using [Scapy](https://github.com/secdev/scapy) with `gtpu-traffic-generator.py`  in `Linux #1`
-- Open other terminal tab in `Linux #0`
-- Check logs: `sudo cat /sys/kernel/debug/tracing/trace | grep "GPDU"`  in `Linux #0`
+These points are achieved mainly by eBPF/XDP and CO-RE (Compile Once - Run Everywhere) technologies.
 
-### Make Commands
+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)
 
-```
-- all                            Build all
-- clean                          Clean all build files
-- all-verbose                    Build all in verbose mode
-- config-veth-pair               Config veth pair. It must be run before `run-*` targets
-- run-hello-world-samples        Build all and run BPF XDP hello world sample
-- run-redirect-map-sample        Build all and run BPF XDP redirect sample
-- run                            Build all and run BPF XDP UPF
-- run-scapy                      Run scapy for packet manipulation
-- force-xdp-deload               Force deload XDP programs
-```
+The main goal is to enable in-kernel fast packet processing in third-party UPF/5G or SPGWu/LTE components in order to:
+1. Boost them for those which does not have any fast packet processing enabled, or
+2. 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.
+
+## Design
+
+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.
+
+<img src="img/up-ebpf-xdp-high-level.svg" alt="drawing" width="500"/>
+
+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.
+
+<img src="img/up-ebpf-xdp-high-level2.svg" alt="drawing" width="500"/>
+
+A low-level design (Datapath Layer) is shown below.
+
+<img src="img/up-ebpf-xdp-low-level.svg" alt="drawing" width="500"/>
+
+## Features
+
+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)
 
-## Dependencies
+Fast Datapath Layer
+- UDP and GTP parse
+- Traffic classification based on PDR
+- Traffic fowarding based on FAR
 
-Upee
+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.
+
+<img src="img/up-ebpf-xdp-ies.svg" alt="drawing" width="600"/>
+
+### WIP
+
+Management Layer - CRUD
+- QER (QoS Enforcement Rule)
+
+Fast Datapath Layer
+- Policy Enforcement based on QER
+
+## Main Dependencies
+
+Core
 - libbpf
-- libelf
-- libz
+- bpftool
+- spdlog
 - clang >= version 3.4.0
 - llvm >= version 3.7.1
 - kernel-headers => version 5.3
-- bpftool
+- cmake >= 3.16
 
 Test
 - scapy v2.4.3
-- spdlog
 - gtest
 - sysstat
 - trex v2.86
 
+## First Steps
+
+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](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.
+
+Inside the container, compile the dependencies with
+
+```
+make setup
+```
+
+## Build and Installation
+
+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
+```
+
+## How to test the software
+
+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](https://www.youtube.com/watch?v=6KYFDMJJH2o) to see the performance evaluation (deprecated).
+
 ## Tree
 
 The directory structure was created based on this [notes](https://blogs.oracle.com/linux/notes-on-bpf-4).
@@ -66,13 +145,23 @@ The directory structure was created based on this [notes](https://blogs.oracle.c
 └── src: Source files directory
 ```
 
-## TRex 
+## TRex
 
 If you faced the problem below, create a symbolic from `libc.a -> liblibc.a`
 `No such file or directory: b'liblibc.a'`
 
+## Contribute
+
+If you think this could be better, **please open an issue or start a discussion**.
+
 ## Contact
 
-Thiago Navarro
-Email: [email protected]
-Twitter: navarr0thiag0
+- [Discord Server](https://discord.gg/TtdUvnA4nq)
+- Mail: <navarro (dot) ime (at) gmail [dot] com>
+- GitHub: [@navarrothiago](https://github.com/navarrothiago/)
+- Twitter: [@navarr0thiag0](https://twitter.com/navarr0thiag0)
+
+## References
+
+- [Author M.Sc. Qualification](https://docs.google.com/presentation/d/1Q24M4Ce8TPPhiM305_Oxs0iQFmmukKwSKdlNcJ0T2uo/edit#slide=id.gc2b6cd2cb2_0_92)
+- [Performance Evaluation with UPF eBPF/XDP Library for 5G Core Network](https://www.youtube.com/watch?v=6KYFDMJJH2o)