Installation

The BNG Blaster should run on any modern Linux distribution but is built and tested on Ubuntu 22.04, 24.04 and 26.04 LTS and Debian Bookworm and Trixie.

Install Ubuntu

Install dependencies:

sudo apt install -y libssl3 libncurses6 libjansson4

Download and install the Debian package: https://github.com/rtbrick/bngblaster/releases

sudo dpkg -i <package>

This command installs the BNG Blaster to /usr/bin/bngblaster. The Debian package also creates compatibility symlinks in /usr/sbin for bngblaster, bngblaster-cli and lspgen.

Container Image

A container image (amd64) with the BNG Blaster, the tools bngblaster-cli, lspgen, bgpupdate and ldpupdate and the BNG Blaster controller is published to the GitHub Container Registry: https://github.com/rtbrick/bngblaster/pkgs/container/bngblaster

The following tags are available:

  • latest: latest release

  • <version>: specific release (e.g. 1.0.1)

  • dev: latest commit on the dev branch

docker pull ghcr.io/rtbrick/bngblaster:latest

The image starts the controller, which provides the REST API and web UI on port 8001. The BNG Blaster needs direct access to the network interfaces used for testing, therefore the container should be started in the host network namespace with the capabilities to send raw packets and change interface settings.

docker run -d --name bngblaster \
    --network host --cap-add NET_ADMIN --cap-add NET_RAW \
    -v $PWD/instances:/var/bngblaster \
    ghcr.io/rtbrick/bngblaster:latest

The web UI is then available at http://<host>:8001/. The instance directory /var/bngblaster can be mounted as shown above to provide configurations and additional files (e.g. MRT files) and to access logs, reports and captures of the test instances directly.

Additional controller options can be passed as command, e.g. to listen on another port or to disable the web UI and file upload:

docker run -d --name bngblaster \
    --network host --cap-add NET_ADMIN --cap-add NET_RAW \
    ghcr.io/rtbrick/bngblaster:latest -addr :8080 -ui=false -upload=false

The BNG Blaster can also be started directly without the controller by overriding the entrypoint:

docker run -it --rm \
    --network host --cap-add NET_ADMIN --cap-add NET_RAW \
    -v $PWD:/work -w /work \
    --entrypoint bngblaster \
    ghcr.io/rtbrick/bngblaster:latest -C config.json -I

The image can also be built locally from the repository root using the provided docker/Dockerfile.

docker build -f docker/Dockerfile -t bngblaster .

Build from Sources

Dependencies

The BNG Blaster has dependencies on the RtBrick libdict fork and the following standard dependencies:

sudo apt install -y wget unzip

# install libdict 1.0.7, where <os> is one of
# ubuntu-22.04, ubuntu-24.04, ubuntu-26.04, bookworm or trixie
wget https://github.com/rtbrick/libdict/releases/download/1.0.7/libdict-<os>.zip
unzip libdict-<os>.zip
sudo dpkg -i libdict_1.0.7_amd64.deb
sudo dpkg -i libdict-dev_1.0.7_amd64.deb

# install other dependencies
sudo apt install -y build-essential cmake \
    libpcap-dev \
    libncurses-dev \
    libssl-dev \
    libjansson-dev

Build

Per default cmake (cmake .) will build the BNG Blaster as a release version with optimization and debug symbols (RelWithDebInfo).

git clone https://github.com/rtbrick/bngblaster.git
cd bngblaster
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
make all

Alternative it is also possible to build a debug version without optimization for detailed troubleshooting using gdb.

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make all

There are also CPack files generated which allow to easily generate a Debian package by just executing cpack from the build directory.

It is also recommended to provide the GIT commit details to be included when manually building the version, as shown below:

cmake -DGIT_REF=`git rev-parse --abbrev-ref HEAD` -DGIT_SHA=`git rev-parse HEAD` .

Example:

$ bngblaster -v
GIT:
  REF: dev
  SHA: df453a5ee9dbf6440aefbfb9630fa0f06e326d44
IO Modes: packet_mmap_raw (default), packet_mmap, raw, loopback

Install

Then BNG Blaster can be installed using the make install target.

sudo make install

This command installs bngblaster, bngblaster-cli, lspgen, bgpupdate and ldpupdate to /usr/bin.

Build Options

The following cmake options are disabled by default:

  • BNGBLASTER_TESTS: build unit tests (requires CMocka)

  • BNGBLASTER_INTEGRATION_TESTS: add integration tests (requires root, pytest, GoBGP, FRR and BIRD)

  • BNGBLASTER_CPU_NATIVE: optimize for the native CPU of the build host (-march=native), the binary might not run on other CPUs

  • BNGBLASTER_TIMER_LOGGING: enable the timer and timer-detail logging flags

  • BNGBLASTER_DPDK: build with DPDK support

  • BNGBLASTER_AF_XDP: build with AF_XDP support

Build and Run Unit Tests

Building and running unit tests requires CMocka to be installed:

sudo apt install libcmocka-dev

The option BNGBLASTER_TESTS enables to build unit tests.

cmake -DCMAKE_BUILD_TYPE=Debug -DBNGBLASTER_TESTS=ON .
make all
make test

Example:

$ make test
Running tests...
Test project
    Start 1: TestUtils
1/4 Test #1: TestUtils ........................   Passed    0.00 sec
    Start 2: TestChecksum
2/4 Test #2: TestChecksum .....................   Passed    0.00 sec
    Start 3: TestTimer
3/4 Test #3: TestTimer ........................   Passed    0.00 sec
    Start 4: TestProtocols
4/4 Test #4: TestProtocols ....................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 4

Total Test time (real) =   0.00 sec

Build with DPDK Support

The following steps are required to build the BNG Blaster with experimental DPDK support.

Note

Tested with DPDK version 25.11.3 and Ubuntu 22.04 (LTS)!

Download and install DPDK: https://doc.dpdk.org/guides/linux_gsg/build_dpdk.html

# install meson and libnuma
sudo apt install meson ninja-build libnuma-dev

# download DPDK
wget https://fast.dpdk.org/rel/dpdk-25.11.tar.xz
tar xJf dpdk-25.11.tar.xz
cd dpdk-25.11

# build with driver SDK
meson -Denable_driver_sdk=true build
cd build
ninja

# install
sudo ninja install
sudo ldconfig

Building BNG Blaster with DPDK support works as explained before but with the additional cmake argument -DBNGBLASTER_DPDK=on

cmake -DBNGBLASTER_DPDK=on ..

If DPDK is installed correctly, cmake should show the following output:

-- Build bngblaster with DPDK support
-- Found PkgConfig: /usr/bin/pkg-config (found version "1.8.0")
-- Checking for module 'libdpdk'
--   Found libdpdk, version 25.11.0
-- Found DPDK via pkg-config

The installed version should now show dpdk as new IO mode.

sudo bngblaster -v
Version: DEV
Compiler: GNU (11.2.0)
IO Modes: packet_mmap_raw (default), packet_mmap, raw, loopback, dpdk

Build with AF_XDP Support

The following steps are required to build the BNG Blaster with experimental AF_XDP support.

Note

Tested with libbpf version 0.5.0 and Ubuntu 22.04 (LTS)!

Install libbpf development files (which include the AF_XDP helper library):

sudo apt install libbpf-dev

The AF_XDP helper library (xsk.h) was removed from libbpf with version 1.0 and moved to libxdp. With libbpf 1.0 or newer (e.g. Ubuntu 24.04 or Debian 12), install the libxdp development files instead, which are preferred if found:

sudo apt install libbpf-dev libxdp-dev

Building BNG Blaster with AF_XDP support works as explained before but with the additional cmake argument -DBNGBLASTER_AF_XDP=on

cmake -DBNGBLASTER_AF_XDP=on ..

If libbpf is installed correctly, cmake should show the following output:

-- Build bngblaster with AF_XDP support
-- Found PkgConfig: /usr/bin/pkg-config (found version "1.8.0")
-- Checking for module 'libbpf'
--   Found libbpf, version 0.5.0
-- Found libbpf 0.5.0 via pkg-config

With libxdp, cmake shows Found libxdp <version> via pkg-config instead.

The installed version should now show af_xdp as new IO mode.

sudo bngblaster -v
Version: DEV
Compiler: GNU (11.4.0)
IO Modes: packet_mmap_raw (default), packet_mmap, raw, loopback, af_xdp

Running BNG Blaster

The BNG Blaster needs permission to send raw packets and change network interface settings. The easiest way to run the BNG Blaster is either as the root user or with sudo:

# As root
bngblaster -C config.json -I

# As a normal user:
sudo bngblaster -C config.json -I

A third option is to set capabilities on the binary with for example setcap as shown below:

sudo setcap cap_net_raw,cap_net_admin,cap_dac_read_search+eip `which bngblaster`

# As normal user:
bngblaster -C config.json -I