mirror/rtbrick-bngblaster
1
0
Fork 0
mirror of https://github.com/rtbrick/bngblaster.git synced 2024-05-06 15:54:57 +00:00
Code Issues Projects Releases Wiki Activity
Files
2b554dbb8cb21374be34f701a47468e4fba3aa42
rtbrick-bngblaster/docs/install.html
Christian Giese 154412bbb2 update github pages
2022-11-02 17:52:51 +01:00

308 lines
14 KiB
HTML
Raw Blame History

<!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" />
<title>Installation &mdash; BNG Blaster 0.8 documentation</title>
<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="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" >
<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 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>
<li class="toctree-l3"><a class="reference internal" href="#build-with-dpdk-support">Build with DPDK Support</a></li>
</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>
<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"><a class="reference internal" href="controller.html">Controller</a></li>
<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference/index.html">Reference</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> &raquo;</li>
<li>Installation</li>
<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">
<span id="install"></span><h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h1>
<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>
<section id="install-ubuntu">
<h2>Install Ubuntu<a class="headerlink" href="#install-ubuntu" title="Permalink to this headline"></a></h2>
<p>Install dependencies:</p>
<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
sudo apt install -y libssl1.1 libncurses5 libjansson4
</pre></div>
</div>
<p>Download and install Debian package: <a class="reference external" href="https://github.com/rtbrick/bngblaster/releases">https://github.com/rtbrick/bngblaster/releases</a></p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo dpkg -i &lt;package&gt;
</pre></div>
</div>
<p>This command installs the BNG Blaster to <cite>/usr/sbin/bngblaster</cite>.</p>
</section>
<section id="build-from-sources">
<h2>Build from Sources<a class="headerlink" href="#build-from-sources" title="Permalink to this headline"></a></h2>
<section id="dependencies">
<h3>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline"></a></h3>
<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># libdict
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
# standard dependencies
sudo apt install -y cmake \
libcunit1-dev \
libncurses5-dev \
libssl-dev \
libjansson-dev
</pre></div>
</div>
</section>
<section id="build">
<h3>Build<a class="headerlink" href="#build" title="Permalink to this headline"></a></h3>
<p>Per default cmake (<cite>cmake .</cite>) will build the BNG Blaster as a release
version with optimization and without debugging symbols.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/rtbrick/bngblaster.git
cd bngblaster
mkdir build
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>
<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>
<p>It is also recommended to provide the GIT commit details to be included in the
manually build the version as shown below:</p>
<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">
<h3>Install<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h3>
<p>Then BNG Blaster can be installed using the make install target.</p>
<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">
<h3>Build and Run Unit Tests<a class="headerlink" href="#build-and-run-unit-tests" title="Permalink to this headline"></a></h3>
<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>
<section id="build-with-dpdk-support">
<span id="install-dpdk"></span><h3>Build with DPDK Support<a class="headerlink" href="#build-with-dpdk-support" title="Permalink to this headline"></a></h3>
<p>The following steps are required to build the BNG Blaster with experimental
<a class="reference external" href="https://www.dpdk.org/">DPDK</a> support.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Tested with DPDK version 21.11.2 (LTS) and Ubuntu 22.04 (LTS)!</p>
</div>
<p>Download and Install DPDK:
<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
wget https://fast.dpdk.org/rel/dpdk-21.11.2.tar.xz
tar xJf dpdk-21.11.2.tar.xz
cd dpdk-stable-21.11.2
# build
meson build
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
-- Found PkgConfig: /usr/bin/pkg-config (found version &quot;0.29.2&quot;)
-- Checking for module &#39;libdpdk&#39;
-- Found libdpdk, version 21.11.2
-- 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>
</section>
<section id="running-bng-blaster">
<h2>Running BNG Blaster<a class="headerlink" href="#running-bng-blaster" title="Permalink to this headline"></a></h2>
<p>The BNG Blaster needs permission to send raw packets and change network interface
settings. The easiest way to run the BNG Blaster is either as the root user or with
sudo:</p>
<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>
<p>A third option is to set capabilities on the binary with for example <cite>setcap</cite>
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">
<p>&#169; 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>
Reference in New Issue View Git Blame Copy Permalink