2022-04-01 12:16:46 +02:00
<!DOCTYPE html>
2024-03-25 22:01:36 +00:00
< html class = "writer-html5" lang = "en" data-content_root = "./" >
2022-04-01 12:16:46 +02:00
< head >
2024-03-25 22:01:36 +00:00
< meta charset = "utf-8" />< meta name = "viewport" content = "width=device-width, initial-scale=1" />
2022-04-01 12:16:46 +02:00
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" />
2022-10-31 23:26:32 +00:00
< title > Installation — BNG Blaster 0.8 documentation</ title >
2024-03-25 22:01:36 +00:00
< link rel = "stylesheet" type = "text/css" href = "_static/pygments.css?v=80d5e7a1" />
< link rel = "stylesheet" type = "text/css" href = "_static/css/theme.css?v=19f00094" />
< link rel = "stylesheet" type = "text/css" href = "_static/tabs.css?v=a5c4661c" />
< link rel = "stylesheet" type = "text/css" href = "_static/custom.css?v=411f5019" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
2022-04-01 12:16:46 +02:00
2024-03-25 22:01:36 +00:00
< script src = "_static/jquery.js?v=5d32c60e" ></ script >
< script src = "_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c" ></ script >
< script src = "_static/documentation_options.js?v=a0e24af7" ></ script >
< script src = "_static/doctools.js?v=888ff710" ></ script >
< script src = "_static/sphinx_highlight.js?v=dc90522c" ></ script >
2022-04-01 12:16:46 +02:00
< 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 = "Quickstart Guide" href = "quickstart.html" />
< link rel = "prev" title = "BNG Blaster" href = "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" >
2024-03-25 22:01:36 +00:00
< a href = "index.html" class = "icon icon-home" >
BNG Blaster
< img src = "_static/rtbrick_logo.png" class = "logo" alt = "Logo" />
2022-04-01 12:16:46 +02:00
</ a >
< div role = "search" >
< form id = "rtd-search-form" class = "wy-form" action = "search.html" method = "get" >
2024-03-25 22:01:36 +00:00
< input type = "text" name = "q" placeholder = "Search docs" aria-label = "Search docs" />
2022-04-01 12:16:46 +02:00
< 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 current" >< a class = "current reference internal" href = "#" > Installation</ a >< ul >
< li class = "toctree-l2" >< a class = "reference internal" href = "#install-ubuntu" > Install Ubuntu</ a ></ li >
< li class = "toctree-l2" >< a class = "reference internal" href = "#build-from-sources" > Build from Sources</ a >< ul >
< li class = "toctree-l3" >< a class = "reference internal" href = "#dependencies" > Dependencies</ a ></ li >
< li class = "toctree-l3" >< a class = "reference internal" href = "#build" > Build</ a ></ li >
< li class = "toctree-l3" >< a class = "reference internal" href = "#id1" > Install</ a ></ li >
< li class = "toctree-l3" >< a class = "reference internal" href = "#build-and-run-unit-tests" > Build and Run Unit Tests</ a ></ li >
2022-10-31 23:26:32 +00:00
< li class = "toctree-l3" >< a class = "reference internal" href = "#build-with-dpdk-support" > Build with DPDK Support</ a ></ li >
2022-04-01 12:16:46 +02:00
</ ul >
</ li >
< li class = "toctree-l2" >< a class = "reference internal" href = "#running-bng-blaster" > Running BNG Blaster</ a ></ li >
</ ul >
</ 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 >
2023-06-30 11:07:35 +00:00
< li class = "toctree-l1" >< a class = "reference internal" href = "http.html" > HTTP Emulation</ a ></ li >
2023-11-03 08:56:38 +00:00
< li class = "toctree-l1" >< a class = "reference internal" href = "nat.html" > NAT / CGNAT</ a ></ li >
2022-04-01 12:16:46 +02:00
< 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 >
2022-05-02 17:40:37 +02:00
< li class = "toctree-l1" >< a class = "reference internal" href = "controller.html" > Controller</ a ></ li >
2023-02-15 21:24:51 +00:00
< li class = "toctree-l1" >< a class = "reference internal" href = "performance.html" > Performance Guide</ a ></ li >
2022-04-01 12:16:46 +02:00
< 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" >
2024-03-25 22:01:36 +00:00
< li >< a href = "index.html" class = "icon icon-home" aria-label = "Home" ></ a ></ li >
< li class = "breadcrumb-item active" > Installation</ li >
2022-04-01 12:16:46 +02:00
< li class = "wy-breadcrumbs-aside" >
< a href = "_sources/install.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 = "installation" >
2024-03-25 22:01:36 +00:00
< span id = "install" ></ span >< h1 > Installation< a class = "headerlink" href = "#installation" title = "Link to this heading" > </ a ></ h1 >
2022-10-31 23:26:32 +00:00
< p > The BNG Blaster should run on any modern Linux distribution
but is primarily tested on Ubuntu 18.04, 20.04 and 22.04 LTS.</ p >
2022-04-01 12:16:46 +02:00
< section id = "install-ubuntu" >
2024-03-25 22:01:36 +00:00
< h2 > Install Ubuntu< a class = "headerlink" href = "#install-ubuntu" title = "Link to this heading" > </ a ></ h2 >
2022-04-01 12:16:46 +02:00
< p > Install dependencies:</ p >
2022-08-02 08:08:14 +00:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > # Ubuntu 18.04 and 20.04
sudo apt install -y libssl1.1 libncurses5 libjansson4
# Ubuntu 22.04
2022-11-02 10:25:07 +00:00
sudo apt install -y libssl3 libncurses6 libjansson4
2022-04-01 12:16:46 +02:00
</ pre ></ div >
</ div >
2022-11-02 10:25:07 +00:00
< p > Download and install the Debian package: < a class = "reference external" href = "https://github.com/rtbrick/bngblaster/releases" > https://github.com/rtbrick/bngblaster/releases</ a ></ p >
2022-04-01 12:16:46 +02:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > sudo dpkg -i < package>
</ pre ></ div >
</ div >
< p > This command installs the BNG Blaster to < cite > /usr/sbin/bngblaster</ cite > .</ p >
</ section >
< section id = "build-from-sources" >
2024-03-25 22:01:36 +00:00
< h2 > Build from Sources< a class = "headerlink" href = "#build-from-sources" title = "Link to this heading" > </ a ></ h2 >
2022-04-01 12:16:46 +02:00
< section id = "dependencies" >
2024-03-25 22:01:36 +00:00
< h3 > Dependencies< a class = "headerlink" href = "#dependencies" title = "Link to this heading" > </ a ></ h3 >
2024-01-04 23:07:29 +00:00
< p > The BNG Blaster has dependencies on the RtBrick
< a class = "reference external" href = "https://github.com/rtbrick/libdict" > libdict fork</ a >
and the following standard dependencies:</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > # install libdict for Ubuntu 18.04 LTS
wget https://github.com/rtbrick/libdict/releases/download/v1.0.1/libdict-debian.zip
unzip libdict-debian.zip
sudo dpkg -i libdict_1.0.1_amd64.deb
sudo dpkg -i libdict-dev_1.0.1_amd64.deb
# install libdict for Ubuntu 22.04 LTS
wget https://github.com/rtbrick/libdict/releases/download/1.0.3/libdict-ubuntu-22.04.zip
unzip libdict-ubuntu-22.04.zip
sudo dpkg -i libdict_1.0.3_amd64.deb
sudo dpkg -i libdict-dev_1.0.3_amd64.deb
# install other dependencies
2022-04-01 12:16:46 +02:00
sudo apt install -y cmake \
2023-09-08 09:32:57 +00:00
libpcap-dev \
2022-04-01 12:16:46 +02:00
libcunit1-dev \
libncurses5-dev \
libssl-dev \
libjansson-dev
</ pre ></ div >
</ div >
</ section >
< section id = "build" >
2024-03-25 22:01:36 +00:00
< h3 > Build< a class = "headerlink" href = "#build" title = "Link to this heading" > </ a ></ h3 >
2022-10-31 23:26:32 +00:00
< p > Per default cmake (< cite > cmake .</ cite > ) will build the BNG Blaster as a release
version with optimization and without debugging symbols.</ p >
2022-05-25 16:02:12 +00:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > git clone https://github.com/rtbrick/bngblaster.git
2022-04-06 23:03:25 +02:00
cd bngblaster
mkdir build
2022-04-01 12:16:46 +02:00
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make all
</ pre ></ div >
</ div >
< p > Alternative it is also possible to build a debug
version for detailed troubleshooting using gdb.</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make all
</ pre ></ div >
</ div >
2022-10-31 23:26:32 +00:00
< p > There are also CPack files generated which allow to easily generate a Debian
package by just executing < cite > cpack</ cite > from the build directory.</ p >
2022-04-01 12:16:46 +02:00
< p > It is also recommended to provide the GIT commit details to be included in the
2022-10-31 23:26:32 +00:00
manually build the version as shown below:</ p >
2022-04-01 12:16:46 +02:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > cmake -DGIT_REF=`git rev-parse --abbrev-ref HEAD` -DGIT_SHA=`git rev-parse HEAD` .
</ pre ></ div >
</ div >
< p >< em > Example:</ em ></ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > $ bngblaster -v
GIT:
REF: dev
SHA: df453a5ee9dbf6440aefbfb9630fa0f06e326d44
IO Modes: packet_mmap_raw (default), packet_mmap, raw
</ pre ></ div >
</ div >
</ section >
< section id = "id1" >
2024-03-25 22:01:36 +00:00
< h3 > Install< a class = "headerlink" href = "#id1" title = "Link to this heading" > </ a ></ h3 >
2022-10-31 23:26:32 +00:00
< p > Then BNG Blaster can be installed using the make install target.</ p >
2022-04-01 12:16:46 +02:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > sudo make install
</ pre ></ div >
</ div >
< p > This command installs the BNG Blaster to < cite > /usr/sbin/bngblaster</ cite > .</ p >
</ section >
< section id = "build-and-run-unit-tests" >
2024-03-25 22:01:36 +00:00
< h3 > Build and Run Unit Tests< a class = "headerlink" href = "#build-and-run-unit-tests" title = "Link to this heading" > </ a ></ h3 >
2022-04-01 12:16:46 +02:00
< p > Building and running unit tests requires CMocka to be installed:</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > sudo apt install libcmocka-dev
</ pre ></ div >
</ div >
< p > The option < cite > BNGBLASTER_TESTS</ cite > enables to build unit tests.</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > cmake -DCMAKE_BUILD_TYPE=Debug -DBNGBLASTER_TESTS=ON .
make all
make test
</ pre ></ div >
</ div >
< p >< em > Example:</ em ></ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > $ make test
Running tests...
Test project
Start 1: TestProtocols
1/1 Test #1: TestProtocols .................... Passed 0.00 sec
100% tests passed, 0 tests failed out of 1
Total Test time (real) = 0.00 sec
</ pre ></ div >
</ div >
</ section >
2022-10-31 23:26:32 +00:00
< section id = "build-with-dpdk-support" >
2024-03-25 22:01:36 +00:00
< span id = "install-dpdk" ></ span >< h3 > Build with DPDK Support< a class = "headerlink" href = "#build-with-dpdk-support" title = "Link to this heading" > </ a ></ h3 >
2022-10-31 23:26:32 +00:00
< p > The following steps are required to build the BNG Blaster with experimental
2023-02-19 21:41:28 +00:00
< a class = "reference internal" href = "performance.html#dpdk-usage" >< span class = "std std-ref" > DPDK</ span ></ a > support.</ p >
2022-10-31 23:26:32 +00:00
< div class = "admonition note" >
< p class = "admonition-title" > Note</ p >
2024-02-20 20:03:00 +00:00
< p > Tested with DPDK version 22.11.4 and Ubuntu 22.04 (LTS)!</ p >
2023-01-13 16:02:11 +00:00
</ div >
2024-02-20 15:57:36 +00:00
< p > Download and install DPDK:
2022-10-31 23:26:32 +00:00
< a class = "reference external" href = "https://doc.dpdk.org/guides/linux_gsg/build_dpdk.html" > https://doc.dpdk.org/guides/linux_gsg/build_dpdk.html</ a ></ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > # install meson
sudo apt install meson ninja-build
# download DPDK
2024-02-20 15:57:36 +00:00
wget https://fast.dpdk.org/rel/dpdk-22.11.4.tar.xz
tar xJf dpdk-22.11.4.tar.xz
cd dpdk-stable-22.11.4
2022-10-31 23:26:32 +00:00
2024-02-20 15:57:36 +00:00
# build with driver SDK
meson -Denable_driver_sdk=true build
2022-10-31 23:26:32 +00:00
cd build
ninja
# install
sudo ninja install
sudo ldconfig
</ pre ></ div >
</ div >
< p > Building BNG Blaster with DPDK support works as explained before but with
the additional cmake argument < code class = "docutils literal notranslate" >< span class = "pre" > -DBNGBLASTER_DPDK=on</ span ></ code ></ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > cmake -DBNGBLASTER_DPDK=on ..
</ pre ></ div >
</ div >
< p > If DPDK is installed correctly, cmake should show the following output:</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > -- Build bngblaster with DPDK support
2024-02-20 15:57:36 +00:00
-- Found PkgConfig: /usr/bin/pkg-config (found version " 1.8.0" )
2022-10-31 23:26:32 +00:00
-- Checking for module ' libdpdk'
2024-02-20 15:57:36 +00:00
-- Found libdpdk, version 22.11.4
2022-10-31 23:26:32 +00:00
-- Found DPDK via pkg-config
</ pre ></ div >
</ div >
< p > The installed version should now show < cite > dpdk</ cite > as new IO mode.</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > sudo bngblaster -v
Version: DEV
Compiler: GNU (11.2.0)
IO Modes: packet_mmap_raw (default), packet_mmap, raw, dpdk
</ pre ></ div >
</ div >
</ section >
2022-04-01 12:16:46 +02:00
</ section >
< section id = "running-bng-blaster" >
2024-03-25 22:01:36 +00:00
< h2 > Running BNG Blaster< a class = "headerlink" href = "#running-bng-blaster" title = "Link to this heading" > </ a ></ h2 >
2022-10-31 23:26:32 +00:00
< p > The BNG Blaster needs permission to send raw packets and change network interface
2023-01-13 16:02:11 +00:00
settings. The easiest way to run the BNG Blaster is either as the root user or
with < cite > sudo</ cite > :</ p >
2022-04-01 12:16:46 +02:00
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > # As root
bngblaster -C config.json -I
# As a normal user:
sudo bngblaster -C config.json -I
</ pre ></ div >
</ div >
2022-10-31 23:26:32 +00:00
< p > A third option is to set capabilities on the binary with for example < cite > setcap</ cite >
2022-04-01 12:16:46 +02:00
as shown below:</ p >
< div class = "highlight-none notranslate" >< div class = "highlight" >< pre >< span ></ span > sudo setcap cap_net_raw,cap_net_admin,cap_dac_read_search+eip `which bngblaster`
# As normal user:
bngblaster -C config.json -I
</ pre ></ div >
</ div >
</ section >
</ section >
</ div >
</ div >
< footer >< div class = "rst-footer-buttons" role = "navigation" aria-label = "Footer" >
< a href = "index.html" class = "btn btn-neutral float-left" title = "BNG Blaster" accesskey = "p" rel = "prev" >< span class = "fa fa-arrow-circle-left" aria-hidden = "true" ></ span > Previous</ a >
< a href = "quickstart.html" class = "btn btn-neutral float-right" title = "Quickstart Guide" accesskey = "n" rel = "next" > Next < span class = "fa fa-arrow-circle-right" aria-hidden = "true" ></ span ></ a >
</ div >
< hr />
< div role = "contentinfo" >
2024-02-23 20:14:00 +00:00
< p > © Copyright 2020-2024, RtBrick, Inc..</ p >
2022-04-01 12:16:46 +02:00
</ 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 >
