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 >
< li >< p >< cite > interfaces</ cite > interface counters</ p ></ li >
</ ul >
< 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
# HELP sessions_established The number of sessions in state established
# 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
are also labeled with the corresponding interface name.</ p >
2022-06-28 16:36:16 +00:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > # 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
...
</ 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 >
