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
rtbrick-bngblaster/docs/install.html
Christian Giese 48c1dc42eb update github pages
2023-02-19 21:41:28 +00:00

313 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="performance.html">Performance Guide</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="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 libssl3 libncurses6 libjansson4
</pre></div>
</div>
<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>
<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 internal" href="performance.html#dpdk-usage"><span class="std std-ref">DPDK</span></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>It is recommended to install the DPDK development package if possible:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo apt install dpdk libdpdk-dev
</pre></div>
</div>
<p>This package does not support all NIC types (e.g. Mellanox, …),
which requires downloading and installing DPDK manually:
<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 <cite>sudo</cite>:</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-2023, 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