Usage

Usage

packetrusher --help lists the commands, and packetrusher <command> --help their flags. Global flags (--config, --tunnel-backend, --report-json, --metrics-addr) go before the command.

Command	Purpose
ue	One gNB and one UE with a PDU session
gnb	One gNB only
multi-ue	Several UEs, with timers, handovers, loops and runtime controls
control, run-scenario	Drive the UEs of a running multi-ue test
custom-scenario	Run a WebAssembly custom scenario
amf-load-loop, amf-availability	NG Setup load and availability probes

Boolean flags take no separate value: write --tunnel or --tunnel-vrf=false, not --tunnel-vrf false.

Several UEs and gNBs

sudo ./packetrusher multi-ue -n 10                      # 10 UEs on one gNB
sudo ./packetrusher multi-ue -n 10 --dedicatedGnb       # one gNB per UE
sudo ./packetrusher multi-ue -n 2 --timeBeforeXnHandover 5000 --loop

The first UE uses the configured MSIN, gNB ID and N2/N3 addresses; each following UE takes the next MSIN and, with several gNBs, the next gNB, whose N2/N3 addresses are the next IP addresses (add them to the interface beforehand). --numPduSessions sets the PDU sessions per UE, 0 to only register.

User-plane tunnels

multi-ue --tunnel gives each UE a network interface carrying its PDU session; ue does so by default (--disableTunnel to turn it off). Send traffic by binding to the UE's address, e.g. iperf3 -B <UE address> -c <server>, or with --dedicatedGnb --tunnel-vrf (the default) from the UE's VRF: sudo ip vrf exec vrf<MSIN> iperf3 -c <server>.

The global --tunnel-backend flag selects what carries the user plane:

Backend	Needs
ebpf	Linux 6.6, root
gtp5g	The gtp5g kernel module
userspace	Nothing: PacketRusher forwards the packets itself, one TUN device per UE
auto (default)	The first of these available on the host

Only auto falls back: a backend requested by name that is not available is an error. ebpf and gtp5g are the fastest and scale with the number of UEs; with userspace, the UEs of a gNB share one socket, so use --dedicatedGnb when several UEs send traffic at once (figures in the README, which test/real-core/throughput.sh measures on your own setup). The tunnel MTU is the N3 interface MTU minus the 44 bytes of GTP-U overhead, unless ue.tunnelmtu sets it.

IPv6 and dual-stack PDU sessions

Set ue.pdusessiontype to IPv6 or IPv4v6 (default IPv4). The UE takes its IPv6 address in the /64 prefix that the UPF advertises through the tunnel. The IPv6 user plane needs the ebpf or userspace backend; on gtp5g an IPv4v6 session carries IPv4 only.

Runtime controls and JSON scenarios

multi-ue --control-socket <path> creates a Unix socket to trigger procedures while the test runs, and --number-of-gnbs adds gNBs to hand UEs over to:

sudo ./packetrusher multi-ue -n 2 --number-of-gnbs 2 --control-socket /tmp/packetrusher.sock
./packetrusher control --socket /tmp/packetrusher.sock --ue 1 --action wait --timeout 45s
./packetrusher control --socket /tmp/packetrusher.sock --ue 1 --action xn-handover --target 000009
./packetrusher run-scenario --socket /tmp/packetrusher.sock --scenario scenario.json

Actions: inspect (default; every UE without --ue), wait (until registered with its PDU sessions), idle, reconnect, xn-handover and ng-handover (to the --target gNB ID), deregister, register. Each prints the UE's state as JSON once done. A scenario runs actions in order:

{"steps": [
  {"ue": 1, "action": "wait", "timeout_ms": 45000},
  {"ue": 1, "action": "xn-handover", "target": "000009"},
  {"ue": 1, "action": "deregister"}
]}

Procedure results

--report-json <file> writes, on exit, the number of started, successful and failed registrations and PDU session establishments with their latencies. --metrics-addr 127.0.0.1:9090 serves the same counters at /metrics for Prometheus while the test runs.

Versions

packetrusher --version prints the release tag, or the source commit for other builds. Tagged releases come with Linux amd64/arm64 archives and a ghcr.io/hewlettpackard/packetrusher:<tag> image.