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 >
