2022-05-02 17:40:37 +02:00
<!DOCTYPE html>
< html class = "writer-html5" lang = "en" >
< head >
< meta charset = "utf-8" / > < meta name = "generator" content = "Docutils 0.17.1: http://docutils.sourceforge.net/" / >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" / >
2022-10-31 23:26:32 +00:00
< title > Controller — BNG Blaster 0.8 documentation< / title >
2022-05-02 17:40:37 +02:00
< link rel = "stylesheet" href = "_static/pygments.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/css/theme.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/tabs.css" type = "text/css" / >
<!-- [if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif] -->
< script data-url_root = "./" id = "documentation_options" src = "_static/documentation_options.js" > < / script >
< script src = "_static/jquery.js" > < / script >
< script src = "_static/underscore.js" > < / script >
< script src = "_static/doctools.js" > < / script >
< script src = "_static/js/theme.js" > < / script >
< link rel = "index" title = "Index" href = "genindex.html" / >
< link rel = "search" title = "Search" href = "search.html" / >
< link rel = "next" title = "Troubleshooting" href = "troubleshooting.html" / >
< link rel = "prev" title = "API/CLI" href = "api/index.html" / >
< / head >
< body class = "wy-body-for-nav" >
< div class = "wy-grid-for-nav" >
< nav data-toggle = "wy-nav-shift" class = "wy-nav-side" >
< div class = "wy-side-scroll" >
< div class = "wy-side-nav-search" >
< a href = "index.html" class = "icon icon-home" > BNG Blaster
< img src = "_static/rtbrick_logo.png" class = "logo" alt = "Logo" / >
< / a >
< div role = "search" >
< form id = "rtd-search-form" class = "wy-form" action = "search.html" method = "get" >
< input type = "text" name = "q" placeholder = "Search docs" / >
< input type = "hidden" name = "check_keywords" value = "yes" / >
< input type = "hidden" name = "area" value = "default" / >
< / form >
< / div >
< / div > < div class = "wy-menu wy-menu-vertical" data-spy = "affix" role = "navigation" aria-label = "Navigation menu" >
< ul class = "current" >
< li class = "toctree-l1" > < a class = "reference internal" href = "install.html" > Installation< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "quickstart.html" > Quickstart Guide< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "interfaces.html" > Interfaces< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "access/index.html" > Access Protocols< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "routing/index.html" > Routing Protocols< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "streams.html" > Traffic Streams< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "reports.html" > Reports< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "configuration/index.html" > Configuration< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "api/index.html" > API/CLI< / a > < / li >
< li class = "toctree-l1 current" > < a class = "current reference internal" href = "#" > Controller< / a > < ul >
< li class = "toctree-l2" > < a class = "reference internal" href = "#installation" > Installation< / a > < / li >
2022-05-02 23:39:48 +02:00
< li class = "toctree-l2" > < a class = "reference internal" href = "#api" > API< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "#create-test-instance" > Create Test Instance< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#start-test" > Start Test< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#status" > Status< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#command" > Command< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#stop-test" > Stop Test< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#delete-test-instance" > Delete Test Instance< / a > < / li >
2022-06-28 16:36:16 +00:00
< li class = "toctree-l3" > < a class = "reference internal" href = "#metrics" > Metrics< / a > < / li >
2022-05-02 23:39:48 +02:00
< / ul >
< / li >
2022-05-02 17:40:37 +02:00
< / ul >
< / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "troubleshooting.html" > Troubleshooting< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "faq.html" > Frequently Asked Questions< / a > < / li >
< / ul >
< / div >
< / div >
< / nav >
< section data-toggle = "wy-nav-shift" class = "wy-nav-content-wrap" > < nav class = "wy-nav-top" aria-label = "Mobile navigation menu" >
< i data-toggle = "wy-nav-top" class = "fa fa-bars" > < / i >
< a href = "index.html" > BNG Blaster< / a >
< / nav >
< div class = "wy-nav-content" >
< div class = "rst-content" >
< div role = "navigation" aria-label = "Page navigation" >
< ul class = "wy-breadcrumbs" >
< li > < a href = "index.html" class = "icon icon-home" > < / a > » < / li >
< li > Controller< / li >
< li class = "wy-breadcrumbs-aside" >
< a href = "_sources/controller.rst.txt" rel = "nofollow" > View page source< / a >
< / li >
< / ul >
< hr / >
< / div >
< div role = "main" class = "document" itemscope = "itemscope" itemtype = "http://schema.org/Article" >
< div itemprop = "articleBody" >
< section id = "controller" >
< span id = "id1" > < / span > < h1 > Controller< a class = "headerlink" href = "#controller" title = "Permalink to this headline" > < / a > < / h1 >
< p > The BNG Blaster controller provides a REST API to start and stop multiple test instances.
It exposes the BNG Blaster < a class = "reference internal" href = "api/index.html#api" > < span class = "std std-ref" > JSON RPC API< / span > < / a > as REST API and provides endpoints
to download logs and reports.< / p >
< p > < a class = "reference external" href = "https://github.com/rtbrick/bngblaster-controller" > https://github.com/rtbrick/bngblaster-controller< / a > < / p >
< section id = "installation" >
< h2 > Installation< a class = "headerlink" href = "#installation" title = "Permalink to this headline" > < / a > < / h2 >
2022-10-31 23:26:32 +00:00
< p > The BNG Blaster controller should run on any modern Linux distribution
but is primarily tested on Ubuntu 18.04 LTS and Ubuntu 20.04 LTS.< / p >
< p > Download and install Debian package: < a class = "reference external" href = "https://github.com/rtbrick/bngblaster-controller/releases" > https://github.com/rtbrick/bngblaster-controller/releases< / a > < / p >
2022-07-08 06:52:39 +00:00
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > $ wget https://github.com/rtbrick/bngblaster-controller/releases/download/< version> /bngblaster-controller_< version> _amd64.deb
$ sudo dpkg -i bngblaster-controller_< version> _amd64.deb
< / pre > < / div >
< / div >
< p > The corresponding service will be started automatically.< / p >
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > $ systemctl status rtbrick-bngblasterctrl.service
● rtbrick-bngblasterctrl.service - RtBrick BNG Blaster Controller
Loaded: loaded (/lib/systemd/system/rtbrick-bngblasterctrl.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2022-07-01 11:14:01 UTC; 7min ago
Main PID: 682535 (bngblasterctrl)
Tasks: 8 (limit: 309235)
Memory: 2.6M
CGroup: /system.slice/rtbrick-bngblasterctrl.service
└─682535 /usr/local/bin/bngblasterctrl
< / pre > < / div >
< / div >
< p > The BNG Blaster controller listens on port < cite > 8001< / cite > per default,
which can be changed using the argument < cite > -addr< / cite > in the systemd
service unit < cite > /etc/systemd/system/bngblaster-controller.service< / cite > .< / p >
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > $ sudo bngblasterctrl --help
Usage of bngblasterctrl:
-addr string
HTTP network address (default " :8001" )
-color
turn on color of color output
-console
turn on pretty console logging (default true)
-d string
config folder (default " /var/bngblaster" )
-debug
turn on debug logging
-e string
bngblaster executable (default " /usr/sbin/bngblaster" )
< / pre > < / div >
< / div >
2022-05-02 17:40:37 +02:00
< / section >
< section id = "api" >
< h2 > API< a class = "headerlink" href = "#api" title = "Permalink to this headline" > < / a > < / h2 >
2022-05-02 23:39:48 +02:00
< p > OpenAPI: < a class = "reference external" href = "https://rtbrick.github.io/bngblaster-controller/" > https://rtbrick.github.io/bngblaster-controller/< / a > < / p >
< section id = "create-test-instance" >
< h3 > Create Test Instance< a class = "headerlink" href = "#create-test-instance" title = "Permalink to this headline" > < / a > < / h3 >
2022-05-10 20:34:10 +00:00
< p > < cite > PUT /api/v1/instances/< instance-name> < / cite > < / p >
2022-05-02 23:39:48 +02:00
< p > This API endpoint creates a test instance if not already created. The body of this request
is stored as bngblaster configuration (< cite > config.json< / cite > ).< / p >
< p > Each test instance creates a directory in < cite > /var/bngblaster/< instance-name> < / cite > .
This directory contains the following files:< / p >
< ul class = "simple" >
< li > < p > < cite > config.json< / cite > : bngblaster configuration< / p > < / li >
< li > < p > < cite > run.pid< / cite > : bngblaster process ID (if running)< / p > < / li >
< li > < p > < cite > run.json< / cite > : bngblaster arguments< / p > < / li >
< li > < p > < cite > run_report.json< / cite > : bngblaster report (if enabled)< / p > < / li >
< li > < p > < cite > run.pcap< / cite > : bngblaster traffic capture (if enabled)< / p > < / li >
< li > < p > < cite > run.sock< / cite > : bngblaster control socket< / p > < / li >
< li > < p > < cite > run.stderr< / cite > : bngblaster standard error< / p > < / li >
2022-05-03 11:19:49 +02:00
< li > < p > < cite > run.stdout< / cite > : bngblaster standard output< / p > < / li >
2022-05-02 23:39:48 +02:00
< / ul >
< / section >
< section id = "start-test" >
< h3 > Start Test< a class = "headerlink" href = "#start-test" title = "Permalink to this headline" > < / a > < / h3 >
2022-05-10 20:34:10 +00:00
< p > < cite > POST /api/v1/instances/< instance-name> /_start< / cite > < / p >
2022-05-02 23:39:48 +02:00
< p > The start API endpoint will start the bngblaster with the argument options
defined in the body.< / p >
2022-06-28 16:36:16 +00:00
< div class = "highlight-json notranslate" > < div class = "highlight" > < pre > < span > < / span > < span class = "p" > {< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " logging" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "kc" > true< / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " logging_flags" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "p" > [< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "s2" > " error" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "s2" > " ip" < / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "p" > ]< / span > < span class = "w" > < / span >
< span class = "p" > }< / span > < span class = "w" > < / span >
< / pre > < / div >
< / div >
< p > All supported argument options are explained in the OpenAPI schema.< / p >
2022-05-02 23:39:48 +02:00
< / section >
< section id = "status" >
< h3 > Status< a class = "headerlink" href = "#status" title = "Permalink to this headline" > < / a > < / h3 >
2022-05-10 20:34:10 +00:00
< p > < cite > GET /api/v1/instances/< instance-name> < / cite > < / p >
2022-05-02 23:39:48 +02:00
< p > The status API endpoint returns the status of the test.< / p >
< / section >
< section id = "command" >
< h3 > Command< a class = "headerlink" href = "#command" title = "Permalink to this headline" > < / a > < / h3 >
2022-05-10 20:34:10 +00:00
< p > < cite > POST /api/v1/instances/< instance-name> /_command< / cite > < / p >
2022-05-02 23:39:48 +02:00
< p > The JSON body of this API call will be passed to the bngblaster instance
2022-05-03 11:19:49 +02:00
control socket (< cite > /var/bngbnlaster/< instance-name> /run.sock< / cite > ). The result will
2022-05-02 23:39:48 +02:00
be passed back to the client.< / p >
2022-05-03 11:19:49 +02:00
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > 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
}
}'
< / pre > < / div >
< / div >
< div class = "highlight-json notranslate" > < div class = "highlight" > < pre > < span > < / span > < span class = "p" > {< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " status" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "s2" > " ok" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " code" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "mi" > 200< / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " session-info" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "p" > {< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " type" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "s2" > " pppoe" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " session-id" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "mi" > 1< / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " session-state" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "s2" > " Established" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " ..." < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "s2" > " ..." < / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "p" > }< / span > < span class = "w" > < / span >
< span class = "p" > }< / span > < span class = "w" > < / span >
< / pre > < / div >
< / div >
< p > The result code is passed as HTTP response status code.< / p >
< div class = "highlight-json notranslate" > < div class = "highlight" > < pre > < span > < / span > < span class = "p" > {< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " status" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "s2" > " warning" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " code" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "mi" > 404< / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " message" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "s2" > " session not found" < / span > < span class = "w" > < / span >
< span class = "p" > }< / span > < span class = "w" > < / span >
< / pre > < / div >
< / div >
2022-05-02 23:39:48 +02:00
< / section >
< section id = "stop-test" >
< h3 > Stop Test< a class = "headerlink" href = "#stop-test" title = "Permalink to this headline" > < / a > < / h3 >
2022-05-10 20:34:10 +00:00
< p > < cite > POST /api/v1/instances/< instance-name> /_stop< / cite > < / p >
2022-05-02 23:39:48 +02:00
< p > The stop API endpoint will send the SIGINT signal to the corresponding BNG blaster instance (< cite > kill -INT < pid> < / cite > ).< / p >
< / section >
< section id = "delete-test-instance" >
< h3 > Delete Test Instance< a class = "headerlink" href = "#delete-test-instance" title = "Permalink to this headline" > < / a > < / h3 >
2022-05-10 20:34:10 +00:00
< p > < cite > DELETE /api/v1/instances/< instance-name> < / cite > < / p >
2022-05-02 23:39:48 +02:00
< p > This API endpoint deletes the test instance directory. The corresponding
2022-05-03 11:19:49 +02:00
test run is forcefully terminated (< cite > kill -9 < pid> < / cite > ) if running.< / p >
2022-05-02 23:39:48 +02:00
< / section >
2022-06-28 16:36:16 +00:00
< section id = "metrics" >
< h3 > Metrics< a class = "headerlink" href = "#metrics" title = "Permalink to this headline" > < / a > < / h3 >
2022-06-30 08:38:05 +00:00
< p > < cite > GET /metrics< / cite > < / p >
2022-10-31 23:26:32 +00:00
< p > This endpoint returns metrics for all instances in Prometheus text format.< / p >
2022-06-28 16:36:16 +00:00
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > # 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
< / pre > < / div >
< / div >
< p > The metric < cite > instances_total< / cite > counts the number of test instance directories
present and < cite > instances_running< / cite > shows how many of them are running.< / p >
2022-10-31 23:26:32 +00:00
< p > Every metric is labeled with the hostname where the controller is running.< / p >
< p > Per default, there are no metrics per instance. This has to be explicitly
2022-06-28 16:36:16 +00:00
enabled during instance start (< cite > /api/v1/instances/< instance-name> /_start< / cite > )
using the new < cite > metric_flags< / cite > option.< / p >
< div class = "highlight-json notranslate" > < div class = "highlight" > < pre > < span > < / span > < span class = "p" > {< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " logging" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "kc" > true< / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " logging_flags" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "p" > [< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "s2" > " error" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "s2" > " ip" < / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "p" > ],< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "nt" > " metric_flags" < / span > < span class = "p" > :< / span > < span class = "w" > < / span > < span class = "p" > [< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "s2" > " session_counters" < / span > < span class = "p" > ,< / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "s2" > " interfaces" < / span > < span class = "w" > < / span >
< span class = "w" > < / span > < span class = "p" > ]< / span > < span class = "w" > < / span >
< span class = "p" > }< / span > < span class = "w" > < / span >
< / pre > < / div >
< / div >
2022-10-31 23:26:32 +00:00
< p > Currently, the following metrics are supported:< / p >
2022-06-28 16:36:16 +00:00
< ul class = "simple" >
< li > < p > < cite > session_counters< / cite > session statistics< / p > < / li >
2022-11-22 14:57:01 +00:00
< li > < p > < cite > interfaces< / cite > interface/link counters< / p > < / li >
< li > < p > < cite > access_interfaces< / cite > access interface function counters< / p > < / li >
< li > < p > < cite > network_interfaces< / cite > network interface function counters< / p > < / li >
< li > < p > < cite > a10nsp_interfaces< / cite > a10nsp interface function counters< / p > < / li >
< li > < p > < cite > streams< / cite > stream counters< / p > < / li >
2022-06-28 16:36:16 +00:00
< / ul >
2022-11-22 14:57:01 +00:00
< p > The < cite > streams< / cite > metric generates statistics for every stream and direction.
Therefore the < cite > streams< / cite > metric should not be used with massive streams
(e.g. > 10.000 streams) but there is no limit enforced.< / p >
2022-06-28 16:36:16 +00:00
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > # HELP sessions The total number of sessions
# TYPE sessions counter
sessions{hostname=" blaster" ,instance_name=" test" } 10
2022-11-22 14:57:01 +00:00
# HELP sessions_established The number of sessions in the state established
2022-06-28 16:36:16 +00:00
# TYPE sessions_established gauge
sessions_established{hostname=" blaster" ,instance_name=" test" } 10
...
< / pre > < / div >
< / div >
2022-10-31 23:26:32 +00:00
< p > Instance metrics are labeled with the instance name. All interface-specific metrics
2022-11-22 14:57:01 +00:00
are also labeled with the corresponding interface name and type.< / p >
< div class = "highlight-none notranslate" > < div class = "highlight" > < pre > < span > < / span > # HELP interfaces_rx_packets Interface RX packets
# TYPE interfaces_rx_packets counter
interfaces_rx_packets{hostname=" rbfs" ,instance_name=" test" ,interface_name=" eth1" ,interface_type=" Interface" } 163
interfaces_rx_packets{hostname=" rbfs" ,instance_name=" test" ,interface_name=" eth11" ,interface_type=" Network" } 155
interfaces_rx_packets{hostname=" rbfs" ,instance_name=" test" ,interface_name=" eth12" ,interface_type=" Interface" } 158
interfaces_rx_packets{hostname=" rbfs" ,instance_name=" test" ,interface_name=" eth12" ,interface_type=" Access" } 150
2022-06-28 16:36:16 +00:00
...
< / pre > < / div >
< / div >
< / section >
2022-05-02 17:40:37 +02:00
< / section >
< / section >
< / div >
< / div >
< footer > < div class = "rst-footer-buttons" role = "navigation" aria-label = "Footer" >
< a href = "api/index.html" class = "btn btn-neutral float-left" title = "API/CLI" accesskey = "p" rel = "prev" > < span class = "fa fa-arrow-circle-left" aria-hidden = "true" > < / span > Previous< / a >
< a href = "troubleshooting.html" class = "btn btn-neutral float-right" title = "Troubleshooting" accesskey = "n" rel = "next" > Next < span class = "fa fa-arrow-circle-right" aria-hidden = "true" > < / span > < / a >
< / div >
< hr / >
< div role = "contentinfo" >
< p > © Copyright 2020-2022, RtBrick, Inc..< / p >
< / div >
Built with < a href = "https://www.sphinx-doc.org/" > Sphinx< / a > using a
< a href = "https://github.com/readthedocs/sphinx_rtd_theme" > theme< / a >
provided by < a href = "https://readthedocs.org" > Read the Docs< / a > .
< / footer >
< / div >
< / div >
< / section >
< / div >
< script >
jQuery ( function ( ) {
SphinxRtdTheme . Navigation . enable ( true ) ;
} ) ;
< / script >
< / body >
< / html >
