DOCSEARCHbyAlgolia
Submit Docs

PacketRusher

repository·main·Indexed 41 days ago

https://github.com/hewlettpackard/packetrusher

A high-performance 5G Core Network testing tool that simulates User Equipment (UE) and gNodeB to validate control plane procedures and stress test the data plane. It supports N1 (NAS), N2 (NGAP), and N3 (GTP-U) interfaces, enabling UE/gNodeB simulation, PDU Session management, and AMF load testing. The tool utilizes the gtp5g kernel module for high-performance N3 interface support and can be deployed via Go or Docker.

Tokens
7K
Snippets
33
Records
35
Agent score
52%

What's inside PacketRusher

  1. PacketRusher Features Overview

    main

    PacketRusher is a performance testing and automatic validation tool for 5G Core Networks. Key capabilities include:

    • UE/gNodeB Simulation: Simulates multiple UEs (tested up to 10k) and gNodeBs from a single tool.
    • Interface Support: Supports N2 (NGAP), N1 (NAS), and high-performance N3 (GTP-U) interfaces.
    • Control Plane Procedures: Implements SUCI Concealing/Deconcealment (Null-Scheme, Profile A/X25519, Profile B/P-256), UE attach/detach, PDU Session management (up to 15 per UE), Xn/N2 handovers, and GUTI re-registration.
    • High-Performance Data Plane: The N3 interface supports generic traffic (TCP, UDP, Video) with performance reaching roughly 5 GB/s per UE.
    • Traffic Capture: Use the --pcap parameter to capture N1/N2 traffic.
    • Testing Integration: Includes an integrated mocked 5GC/AMF for integration testing.

  2. Run PacketRusher scenarios

    main

    After building the CLI and configuring your settings in $PACKETRUSHER/config/config.yml, you can execute different testing scenarios:

    • Basic Scenario: Run a single User Equipment (UE) simulation using sudo ./packetrusher ue.
    • Complex Scenarios: Run multiple UE simulations using sudo ./packetrusher multi-ue.

    Always run these commands from the $PACKETRUSHER directory with sudo privileges.

    # Basic scenario
$ sudo ./packetrusher ue

# Complex scenario
$ sudo ./packetrusher multi-ue
$ ./packetrusher multi-ue --help

  3. Install and compile the gtp5g kernel module

    main

    The gtp5g module is a customized Linux kernel module designed to handle packets via PFCP IEs (such as PDR and FAR).

    Requirements

    • Kernel Version: Must be 5.0.0-23-generic or higher than 5.4 (e.g., Ubuntu 20.04 or RHEL8).
    • Secure Boot: Ensure Secure Boot is disabled if you are unable to install the custom kernel module.

    Installation Steps

    1. Clone the repository:
      • Latest version: git clone https://github.com/free5gc/gtp5g.git
      • Specific version: git clone -b {version} https://github.com/free5gc/gtp5g.git
    2. Compile:
      cd gtp5g
make clean && make
    3. Install (loads automatically at boot):
      sudo make install

    To remove the module from the system, run:

    sudo make uninstall
    git clone https://github.com/free5gc/gtp5g.git
cd gtp5g
make clean && make
sudo make install

  4. Download and prepare PacketRusher source code

    main

    Clone the repository and set the PACKETRUSHER environment variable to the current working directory to facilitate building and running the tool.

    1. Clone the repo: git clone https://github.com/HewlettPackard/PacketRusher
    2. Set the environment variable: cd PacketRusher && echo "export PACKETRUSHER=$PWD" >> $HOME/.profile
    3. Apply the variable to the current session: source $HOME/.profile
    $ git clone https://github.com/HewlettPackard/PacketRusher
$ cd PacketRusher && echo "export PACKETRUSHER=$PWD" >> $HOME/.profile
$ source $HOME/.profile

  5. Launch the PacketRusher tester with Docker Compose

    main

    To launch the tester, use docker-compose with the configuration file located at docker/docker-compose.yaml.

    Prerequisite: Ensure that your core-network is already set up, as the tester reuses the existing Docker network.

    docker-compose -f docker/docker-compose.yaml up -d

  6. Build the PacketRusher Docker image

    main

    To build the PacketRusher Docker image, use the docker build command from the root of the repository. You must specify the Dockerfile located in the docker/ directory and set the build target to packetrusher.

    docker build -f docker/Dockerfile --target packetrusher --tag packetrusher:latest .

  7. Build the gtp5g kernel module

    main

    PacketRusher requires the gtp5g kernel module (from free5gc) for high-performance N3 (GTP-U) interface support.

    Requirement: You must have Secure Boot disabled if you are unable to install this custom kernel module.

    Navigate to the module directory and run the make commands:

    1. cd $PACKETRUSHER/lib/gtp5g
    2. make clean && make && sudo make install
    $ cd $PACKETRUSHER/lib/gtp5g
$ make clean && make && sudo make install

  8. Install PacketRusher on old RHEL9 versions

    main

    To run PacketRusher on older RHEL9 versions (tested on Rocky-9.0-20220805.0-x86_64-minimal.iso), follow these steps to prepare the environment:

    1. Update Yum Repositories: Point your yum repositories to the archived 9.0 vault.
    2. Install Dependencies: Install essential build tools, kernel headers, and SCTP tools.
    3. Configure SCTP Kernel Module: Enable the sctp module and ensure it is not blacklisted.
    4. Install Golang: Download and install Go 1.21.3. Warning: This process will remove any existing local Go installation at /usr/local/go.
    5. Set Environment Variables: Add the Go binary to your PATH and set the PACKETRUSHER variable to your source directory.

    Note on Secure Boot: If you are unable to install the custom Kernel module, ensure Secure Boot is disabled by checking the status with mokutil --sb-state.

    # 1. Change yum repo to the archived 9.0 one
$ sudo find /etc/yum.repos.d -type f -exec sed -i -e "s,#baseurl=http://dl.rockylinux.org/\$contentdir/\$releasever,baseurl=https://download.rockylinux.org/vault/rocky/9.0,g" {} \;
$ sudo find /etc/yum.repos.d -type f -exec sed -i -e "s,mirrorlist,#mirrorlist,g" {} \;
$ sudo find /etc/yum.repos.d -type f -exec sed -i -e "s,/os/,/kickstart/,g" {} \;

# 2. Install the required packages
$ sudo yum install git wget tar make automake gcc gcc-c++ kernel-devel-$(uname -r) kernel-modules-extra-$(uname -r) lksctp-tools lksctp-tools-devel lksctp-tools-doc mokutil

# 3. Install sctp kernel module
$ echo sctp | sudo tee /etc/modules-load.d/sctp.conf
$ sudo sed -i 's/blacklist sctp/#blacklist sctp/g' /etc/modprobe.d/sctp-blacklist.conf
$ sudo sed -i 's/blacklist sctp_diag/#blacklist sctp_diag/g' /etc/modprobe.d/sctp_diag-blacklist.conf
$ sudo modprobe sctp

# 4. Install Golang (Warning: removes existing /usr/local/go)
$ wget https://go.dev/dl/go1.21.3.linux-amd64.tar.gz && sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.21.3.linux-amd64.tar.gz
$ echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.profile

# 5. Setup PacketRusher environment
$ git clone https://github.com/HewlettPackard/PacketRusher
$ cd PacketRusher && echo "export PACKETRUSHER=$PWD" >> $HOME/.profile
$ source $HOME/.profile

  9. Install PacketRusher dependencies and Go

    main

    Before building PacketRusher, install the necessary system dependencies and the Go programming language.

    Warning: The Go installation command provided below will remove any existing local Go installation at /usr/local/go.

    1. Install system build tools and kernel headers: sudo apt install build-essential linux-headers-generic make git wget tar linux-modules-extra-$(uname -r)
    2. Install Go 1.24.1 (or newer): wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz && sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz
    3. Add Go to your PATH: echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.profile
    $ sudo apt install build-essential linux-headers-generic make git wget tar linux-modules-extra-$(uname -r)
$ wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz && sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz
$ echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.profile

  10. Build the PacketRusher CLI

    main

    Compile the PacketRusher binary using Go. Ensure you have completed the kernel module installation and dependency setup first.

    1. Navigate to the root directory: cd $PACKETRUSHER
    2. Download Go modules: go mod download
    3. Build the binary: go build cmd/packetrusher.go
    4. Verify the build: ./packetrusher --help
    $ cd $PACKETRUSHER
$ go mod download
$ go build cmd/packetrusher.go
$ ./packetrusher --help

  11. Sign your work to accept the DCO

    main

    To contribute to this project, you must accept the Developer Certificate of Origin (DCO) by including a sign-off line in every commit message. This certifies that you have the right to submit the contribution under the project's open source license.

    Each commit must include a line in the following format:

    Signed-off-by: <Name> <email>

    Important: Anonymous or pseudonymous contributions are not accepted for legal reasons.

    # Use the -s flag to automatically add the sign-off line to your commit
git commit -s

  12. Configure QoS and GTP-U Sequence Number settings

    main

    The gtp5g module allows you to enable or disable specific features via the /proc/gtp5g/ interface.

    Quality of Service (QoS)

    Supports Session AMBR and MFBR. Default is disabled.

    • Check status: cat /proc/gtp5g/qos (1 = enabled, 0 = disabled)
    • Enable: echo 1 > /proc/gtp5g/qos
    • Disable: echo 0 > /proc/gtp5g/qos

    GTP-U Sequence Number

    Supports GTP-U Sequence Number. Default is enabled.

    • Check status: cat /proc/gtp5g/seq (1 = enabled, 0 = disabled)
    • Enable: echo 1 > /proc/gtp5g/seq
    • Disable: echo 0 > /proc/gtp5g/seq
    echo 1 > /proc/gtp5g/qos
echo 0 > /proc/gtp5g/seq