Controller

The BNG Blaster controller provides a REST API to start and stop multiple test instances. It exposes the BNG Blaster JSON RPC API as REST API and provides endpoints to download logs and reports.

https://github.com/rtbrick/bngblaster-controller

Installation

The BNG Blaster controller should run on any modern linux distribution but is primary tested on Ubuntu 18.04 LTS and Ubuntu 20.04 LTS.

Download and install debian package: https://github.com/rtbrick/bngblaster-controller/releases

API

OpenAPI: https://rtbrick.github.io/bngblaster-controller/

Create Test Instance

PUT /api/v1/instances/<instance-name>

This API endpoint creates a test instance if not already created. The body of this request is stored as bngblaster configuration (config.json).

Each test instance creates a directory in /var/bngblaster/<instance-name>. This directory contains the following files:

config.json: bngblaster configuration
run.pid: bngblaster process ID (if running)
run.json: bngblaster arguments
run_report.json: bngblaster report (if enabled)
run.pcap: bngblaster traffic capture (if enabled)
run.sock: bngblaster control socket
run.stderr: bngblaster standard error
run.stdout: bngblaster standard output

Start Test

POST /api/v1/instances/<instance-name>/_start

The start API endpoint will start the bngblaster with the argument options defined in the body.

{
    "logging": true,
    "logging_flags": [
        "error",
        "ip"
    ]
}

All supported argument options are explained in the OpenAPI schema.

Status

GET /api/v1/instances/<instance-name>

The status API endpoint returns the status of the test.

Command

POST /api/v1/instances/<instance-name>/_command

The JSON body of this API call will be passed to the bngblaster instance control socket (/var/bngbnlaster/<instance-name>/run.sock). The result will be passed back to the client.

curl --location --request POST 'http://<IP>>:8001/api/v1/instances/<instance-name>/_command' \
--header 'Content-Type: application/json' \
--data-raw '{
    "command": "session-info",
    "arguments": {
        "session-id": 1
    }
}'

{
    "status": "ok",
    "code": 200,
    "session-info": {
        "type": "pppoe",
        "session-id": 1,
        "session-state": "Established",
        "...": "..."
    }
}

The result code is passed as HTTP response status code.

{
    "status": "warning",
    "code": 404,
    "message": "session not found"
}

Stop Test

POST /api/v1/instances/<instance-name>/_stop

The stop API endpoint will send the SIGINT signal to the corresponding BNG blaster instance (kill -INT <pid>).

Delete Test Instance

DELETE /api/v1/instances/<instance-name>

This API endpoint deletes the test instance directory. The corresponding test run is forcefully terminated (kill -9 <pid>) if running.

Metrics

GET /api/v1/instances/metrics

This endpoint returns metrics for all instances in prometheus text format.

# HELP instances_running The number of running instances
# TYPE instances_running gauge
instances_running{hostname="blaster"} 0
# HELP instances_total The total number of instances
# TYPE instances_total gauge
instances_total{hostname="blaster"} 4

The metric instances_total counts the number of test instance directories present and instances_running shows how many of them are running.

Every metric is labelled with the hostname where the controller is running.

Per default there are no metrics per instance. This has to be explicitly enabled during instance start (/api/v1/instances/<instance-name>/_start) using the new metric_flags option.

{
    "logging": true,
    "logging_flags": [
        "error",
        "ip"
    ],
    "metric_flags": [
        "session_counters",
        "interfaces"
    ]
}

Currently the following metrics are supported:

session_counters session statistics
interfaces interface counters

# HELP sessions The total number of sessions
# TYPE sessions counter
sessions{hostname="blaster",instance_name="test"} 10
# HELP sessions_established The number of sessions in state established
# TYPE sessions_established gauge
sessions_established{hostname="blaster",instance_name="test"} 10
...

Instance metrics are labelled with the instance name. All interface specific metrics are also labelled with the corresponding interface name.

# HELP interfaces_rx_bytes Interface RX bytes
# TYPE interfaces_rx_bytes counter
interfaces_rx_bytes{hostname="blaster",instance_name="test",interface_name="eth1",interface_type="access"} 36270
...