IntenseWebs/LibreQoS
3
0
Fork 0
mirror of https://github.com/LibreQoE/LibreQoS.git synced 2024-11-28 19:03:49 -06:00
Code Issues Packages Projects Releases Wiki Activity
binpacking_flat
LibreQoS/_readthedocs/html/docs/Legacy/v1.3.1.html
rchac d22860293e test
2023-05-19 14:17:54 -06:00

581 lines
42 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>LibreQoS v1.3.1 &mdash; LibreQoE documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/theme.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/doctools.js"></script>
<script src="../../_static/sphinx_highlight.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="prev" title="Performance Tuning" href="../TechnicalDocs/performance-tuning.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">
LibreQoE
</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" aria-label="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">
<p class="caption" role="heading"><span class="caption-text">Readme:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../README.html">Sponsors</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../README.html#support-libreqos">Support LibreQoS</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../README.html#documentation">Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../README.html#matrix-chat">Matrix Chat</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../README.html#features">Features</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Read me first!</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../Quickstart/networkdesignassumptions.html">Network Design Assumptions</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Change Notes:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../ChangeNotes/v1.4.html">LibreQoS v1.3.1 to v1.4 Change Summary</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Quickstart:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../SystemRequirements/Compute.html">System Requirements</a></li>
<li class="toctree-l1"><a class="reference internal" href="../SystemRequirements/Networking.html">Network Interface Requirements</a></li>
<li class="toctree-l1"><a class="reference internal" href="../Quickstart/quickstart-prereq.html">Server Setup - Pre-requisites</a></li>
<li class="toctree-l1"><a class="reference internal" href="../Quickstart/quickstart-libreqos-1.4.html">Install LibreQoS 1.4</a></li>
<li class="toctree-l1"><a class="reference internal" href="../Quickstart/share.html">Share your before and after</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Updates:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../Updates/update.html">Updating 1.4 To Latest Version</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Technical Documentation:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../TechnicalDocs/troubleshooting.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="../TechnicalDocs/integrations.html">Integrations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../TechnicalDocs/extras.html">Extras</a></li>
<li class="toctree-l1"><a class="reference internal" href="../TechnicalDocs/performance-tuning.html">Performance Tuning</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Legacy:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">LibreQoS v1.3.1</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#libreqos-v1-3-1-installation-usage-guide-physical-server-and-ubuntu-22-04">LibreQoS v1.3.1 Installation &amp; Usage Guide - Physical Server and Ubuntu 22.04</a></li>
<li class="toctree-l2"><a class="reference internal" href="#notes-for-upgrading-from-v1-2-or-prior">Notes for upgrading from v1.2 or prior</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#custom-crm-integrations">Custom CRM Integrations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#network-design-assumptions">Network Design Assumptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#network-interface-card">Network Interface Card</a></li>
<li class="toctree-l2"><a class="reference internal" href="#server-setup">Server Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="#install-ubuntu">Install Ubuntu</a></li>
<li class="toctree-l2"><a class="reference internal" href="#use-installer-script-for-sponsors-skip-if-not-applicable">Use Installer Script (For Sponsors - Skip If Not Applicable)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#setup">Setup</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#disable-irqbalance">Disable IRQbalance</a></li>
<li class="toctree-l3"><a class="reference internal" href="#disable-offloading">Disable Offloading</a></li>
<li class="toctree-l3"><a class="reference internal" href="#add-a-bridge-between-edge-core-interfaces">Add a bridge between edge/core interfaces</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-libreqos-and-dependencies">Install LibreQoS and dependencies</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-and-compile-cpumap-pping">Install and compile cpumap-pping</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-influxdb-for-graphing">Install InfluxDB for Graphing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#modify-ispconfig-py">Modify ispConfig.py</a></li>
<li class="toctree-l3"><a class="reference internal" href="#integrations">Integrations</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#uisp-integration">UISP Integration</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#network-json">Network.json</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#manual-editing">Manual Editing</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#shapeddevices-csv">ShapedDevices.csv</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#how-to-run-libreqos">How to run LibreQoS</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#one-time-debug-runs">One-Time / Debug Runs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#running-as-a-service">Running as a service</a></li>
<li class="toctree-l3"><a class="reference internal" href="#crontab">Crontab</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#common-issues">Common Issues</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#program-running-but-traffic-not-shaping">Program Running, But Traffic Not Shaping</a></li>
<li class="toctree-l3"><a class="reference internal" href="#rtnetlink-answers-invalid-argument">RTNETLINK answers: Invalid argument</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#performance-tuning">Performance Tuning</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#ospf">OSPF</a></li>
</ul>
</li>
</ul>
</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">LibreQoE</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" aria-label="Home"></a></li>
<li class="breadcrumb-item active">LibreQoS v1.3.1</li>
<li class="wy-breadcrumbs-aside">
<a href="../../_sources/docs/Legacy/v1.3.1.md.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="libreqos-v1-3-1">
<h1>LibreQoS v1.3.1<a class="headerlink" href="#libreqos-v1-3-1" title="Permalink to this heading"></a></h1>
<section id="libreqos-v1-3-1-installation-usage-guide-physical-server-and-ubuntu-22-04">
<h2>LibreQoS v1.3.1 Installation &amp; Usage Guide - Physical Server and Ubuntu 22.04<a class="headerlink" href="#libreqos-v1-3-1-installation-usage-guide-physical-server-and-ubuntu-22-04" title="Permalink to this heading"></a></h2>
</section>
<section id="notes-for-upgrading-from-v1-2-or-prior">
<h2>Notes for upgrading from v1.2 or prior<a class="headerlink" href="#notes-for-upgrading-from-v1-2-or-prior" title="Permalink to this heading"></a></h2>
<section id="custom-crm-integrations">
<h3>Custom CRM Integrations<a class="headerlink" href="#custom-crm-integrations" title="Permalink to this heading"></a></h3>
<p>If you use a custom CRM integration, please ensure your integration uses a unique circuit identifier for the ‘Circuit ID’ field in ShapedDevices.csv. This is now required in v1.3 in order to make partial reloading possible. A good choice for this ID would be internet service plan unique ID, or the subscriber site ID your CRM provides for customer service locations. Multiple devices within the same circuit would use the same ‘Circuit ID’, but aside from that, all Circuit IDs should be distinct. The built-in Splynx and UISP integrations for v1.3 handle this automatically.</p>
</section>
</section>
<section id="network-design-assumptions">
<h2>Network Design Assumptions<a class="headerlink" href="#network-design-assumptions" title="Permalink to this heading"></a></h2>
<p>Officially supported configuration:</p>
<ul class="simple">
<li><p>Edge and Core routers with MTU 1500 on links between them</p></li>
<li><p>If you use MPLS, you would terminate MPLS traffic at the core router.
LibreQoS cannot decapsulate MPLS on its own.</p></li>
<li><p>OSPF primary link (low cost) through the server running LibreQoS</p></li>
<li><p>OSPF backup link</p></li>
</ul>
<p><img alt="" src="https://raw.githubusercontent.com/rchac/LibreQoS/main/docs/design.png" /></p>
<p>Is it possible to use LibreQoS in-line without a core router, but that setup requires depending on STP instead of OSPF, which can cause issues. Such configurations are not officially supported.</p>
</section>
<section id="network-interface-card">
<h2>Network Interface Card<a class="headerlink" href="#network-interface-card" title="Permalink to this heading"></a></h2>
<p>LibreQoS requires a NIC with 2 or more RX/TX queues and XDP support. While many cards theoretically meet these requirements, less commonly used cards tend to have unreported driver bugs which impede XDP functionality and make them unusable for our purposes. At this time we can only recommend Intel x520, Intel x710, and Nvidia (ConnectX-5 or newer) NICs.</p>
</section>
<section id="server-setup">
<h2>Server Setup<a class="headerlink" href="#server-setup" title="Permalink to this heading"></a></h2>
<p>Disable hyperthreading on the BIOS/UEFI of your host system. Hyperthreaading is also known as Simultaneous Multi Threading (SMT) on AMD systems. Disabling this is very important for optimal performance of the XDP cpumap filtering and, in turn, throughput and latency.</p>
<ul class="simple">
<li><p>Boot, pressing the appropriate key to enter the BIOS settings</p></li>
<li><p>For AMD systems, you will have to navigate the settings to find the “SMT Control” setting. Usually it is under something like <code class="docutils literal notranslate"><span class="pre">Advanced</span> <span class="pre">-&gt;</span> <span class="pre">AMD</span> <span class="pre">CBS</span> <span class="pre">-&gt;</span> <span class="pre">CPU</span> <span class="pre">Common</span> <span class="pre">Options</span> <span class="pre">-&gt;</span> <span class="pre">Thread</span> <span class="pre">Enablement</span> <span class="pre">-&gt;</span> <span class="pre">SMT</span> <span class="pre">Control</span></code> Once you find it, switch to “Disabled” or “Off”</p></li>
<li><p>For Intel systems, you will also have to navigate the settings to find the “hyperthrading” toggle option. On HP servers it’s under <code class="docutils literal notranslate"><span class="pre">System</span> <span class="pre">Configuration</span> <span class="pre">&gt;</span> <span class="pre">BIOS/Platform</span> <span class="pre">Configuration</span> <span class="pre">(RBSU)</span> <span class="pre">&gt;</span> <span class="pre">Processor</span> <span class="pre">Options</span> <span class="pre">&gt;</span> <span class="pre">Intel</span> <span class="pre">(R)</span> <span class="pre">Hyperthreading</span> <span class="pre">Options.</span></code></p></li>
<li><p>Save changes and reboot</p></li>
</ul>
</section>
<section id="install-ubuntu">
<h2>Install Ubuntu<a class="headerlink" href="#install-ubuntu" title="Permalink to this heading"></a></h2>
<p>Download Ubuntu Server 22.04 from <a href="https://ubuntu.com/download/server">https://ubuntu.com/download/server</a>.</p>
<ol class="arabic simple">
<li><p>Boot Ubuntu Server from USB.</p></li>
<li><p>Follow the steps to install Ubuntu Server.</p></li>
<li><p>If you use a Mellanox network card, the Ubuntu Server installer will ask you whether to install the mellanox/intel NIC drivers. Check the box to confirm. This extra driver is important.</p></li>
<li><p>On the Networking settings step, it is recommended to assign a static IP address to the management NIC.</p></li>
<li><p>Ensure SSH server is enabled so you can more easily log into the server later.</p></li>
<li><p>You can use scp or sftp to access files from your LibreQoS server for easier file editing. Here’s how to access via scp or sftp using an <a class="reference external" href="https://www.addictivetips.com/ubuntu-linux-tips/sftp-server-ubuntu/">Ubuntu</a> or <a class="reference external" href="https://winscp.net/eng/index.php">Windows</a> machine.</p></li>
</ol>
</section>
<section id="use-installer-script-for-sponsors-skip-if-not-applicable">
<h2>Use Installer Script (For Sponsors - Skip If Not Applicable)<a class="headerlink" href="#use-installer-script-for-sponsors-skip-if-not-applicable" title="Permalink to this heading"></a></h2>
<p>Sponsors can use the LibreQoS-Installer script. This script does the following:</p>
<ul class="simple">
<li><p>Disables IRQbalance</p></li>
<li><p>Disables required offloading types using service</p></li>
<li><p>Creates a bridge between two interfaces - applied by the above service at each boot</p></li>
<li><p>Installs LibreQoS and cpumap-pping</p></li>
</ul>
<p>Once complete - skip to <a class="reference external" href="https://github.com/LibreQoE/LibreQoS/wiki/LibreQoS-v1.3-Installation-&amp;amp;-Usage-Guide-Physical-Server-and-Ubuntu-22.04#install-influxdb-for-graphing">this section</a> of the guide.</p>
</section>
<section id="setup">
<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this heading"></a></h2>
<section id="disable-irqbalance">
<h3>Disable IRQbalance<a class="headerlink" href="#disable-irqbalance" title="Permalink to this heading"></a></h3>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>systemctl<span class="w"> </span>stop<span class="w"> </span>irqbalance
sudo<span class="w"> </span>systemctl<span class="w"> </span>disable<span class="w"> </span>irqbalance
</pre></div>
</div>
</section>
<section id="disable-offloading">
<h3>Disable Offloading<a class="headerlink" href="#disable-offloading" title="Permalink to this heading"></a></h3>
<p>We need to disable certain hardware offloading features, as they break XDP, used by XDP-CPUMAP-TC to send traffic to appropriate CPUs.
You can create a bash script to disabled these offload features upon boot.</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>nano<span class="w"> </span>/usr/local/sbin/offloadOff.sh
</pre></div>
</div>
<p>Enter the following</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span>
ethtool<span class="w"> </span>--offload<span class="w"> </span>eth1<span class="w"> </span>gso<span class="w"> </span>off<span class="w"> </span>tso<span class="w"> </span>off<span class="w"> </span>lro<span class="w"> </span>off<span class="w"> </span>sg<span class="w"> </span>off<span class="w"> </span>gro<span class="w"> </span>off
ethtool<span class="w"> </span>--offload<span class="w"> </span>eth2<span class="w"> </span>gso<span class="w"> </span>off<span class="w"> </span>tso<span class="w"> </span>off<span class="w"> </span>lro<span class="w"> </span>off<span class="w"> </span>sg<span class="w"> </span>off<span class="w"> </span>gro<span class="w"> </span>off
</pre></div>
</div>
<p>Replace eth1 and eth2 with your two shaper interfaces (order doesn’t matter).
Then create</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>nano<span class="w"> </span>/etc/systemd/system/offloadOff.service
</pre></div>
</div>
<p>With the following</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[Unit]
After=network.service
[Service]
ExecStart=/usr/local/sbin/offloadOff.sh
[Install]
WantedBy=default.target
</pre></div>
</div>
<p>Then change permissions and enable the service with</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>chmod<span class="w"> </span><span class="m">664</span><span class="w"> </span>/etc/systemd/system/offloadOff.service
sudo<span class="w"> </span>chmod<span class="w"> </span><span class="m">744</span><span class="w"> </span>/usr/local/sbin/offloadOff.sh
sudo<span class="w"> </span>systemctl<span class="w"> </span>daemon-reload
sudo<span class="w"> </span>systemctl<span class="w"> </span><span class="nb">enable</span><span class="w"> </span>offloadOff.service
sudo<span class="w"> </span>reboot
</pre></div>
</div>
</section>
<section id="add-a-bridge-between-edge-core-interfaces">
<h3>Add a bridge between edge/core interfaces<a class="headerlink" href="#add-a-bridge-between-edge-core-interfaces" title="Permalink to this heading"></a></h3>
<p>From the Ubuntu VM, create a linux interface bridge - br0 - with the two shaping interfaces.
Find your existing .yaml file in /etc/netplan/ with</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>/etc/netplan/
ls
</pre></div>
</div>
<p>Then edit the .yaml file there with</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>nano<span class="w"> </span>XX-cloud-init.yaml
</pre></div>
</div>
<p>with XX corresponding to the name of the existing file.</p>
<p>Editing the .yaml file, we need to define the shaping interfaces (here, ens19 and ens20) and add the bridge with those two interfaces. Assuming your interfaces are ens18, ens19, and ens20, here is what your file might look like:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is the network config written by &#39;subiquity&#39;</span>
<span class="nt">network</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ethernets</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ens18</span><span class="p">:</span>
<span class="w"> </span><span class="nt">addresses</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10.0.0.12/24</span>
<span class="w"> </span><span class="nt">routes</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">default</span>
<span class="w"> </span><span class="nt">via</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10.0.0.1</span>
<span class="w"> </span><span class="nt">nameservers</span><span class="p">:</span>
<span class="w"> </span><span class="nt">addresses</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1.1.1.1</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8.8.8.8</span>
<span class="w"> </span><span class="nt">search</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[]</span>
<span class="w"> </span><span class="nt">ens19</span><span class="p">:</span>
<span class="w"> </span><span class="nt">dhcp4</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">no</span>
<span class="w"> </span><span class="nt">ens20</span><span class="p">:</span>
<span class="w"> </span><span class="nt">dhcp4</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">no</span>
<span class="w"> </span><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="w"> </span><span class="nt">bridges</span><span class="p">:</span>
<span class="w"> </span><span class="nt">br0</span><span class="p">:</span>
<span class="w"> </span><span class="nt">interfaces</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ens19</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ens20</span>
</pre></div>
</div>
<p>Make sure to replace 10.0.0.12/24 with your LibreQoS VM’s address and subnet, and to replace the default gateway 10.0.0.1 with whatever your default gateway is.</p>
<p>Then run</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>netplan<span class="w"> </span>apply
</pre></div>
</div>
</section>
<section id="install-libreqos-and-dependencies">
<h3>Install LibreQoS and dependencies<a class="headerlink" href="#install-libreqos-and-dependencies" title="Permalink to this heading"></a></h3>
<p>Cd to your preferred directory and download the latest release</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>home/<span class="nv">$USER</span>/
sudo<span class="w"> </span>apt<span class="w"> </span>update
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3-pip<span class="w"> </span>clang<span class="w"> </span>gcc<span class="w"> </span>gcc-multilib<span class="w"> </span>llvm<span class="w"> </span>libelf-dev<span class="w"> </span>git<span class="w"> </span>nano<span class="w"> </span>graphviz
python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
sudo<span class="w"> </span>python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
git<span class="w"> </span>clone<span class="w"> </span>https://github.com/rchac/LibreQoS.git
git<span class="w"> </span>checkout<span class="w"> </span>v1.3.1
</pre></div>
</div>
</section>
<section id="install-and-compile-cpumap-pping">
<h3>Install and compile cpumap-pping<a class="headerlink" href="#install-and-compile-cpumap-pping" title="Permalink to this heading"></a></h3>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>home/<span class="nv">$USER</span>/LibreQoS/src
git<span class="w"> </span>submodule<span class="w"> </span>update<span class="w"> </span>--init
<span class="nb">cd</span><span class="w"> </span>cpumap-pping/
git<span class="w"> </span>submodule<span class="w"> </span>update<span class="w"> </span>--init
<span class="nb">cd</span><span class="w"> </span>src/
make
</pre></div>
</div>
</section>
<section id="install-influxdb-for-graphing">
<h3>Install InfluxDB for Graphing<a class="headerlink" href="#install-influxdb-for-graphing" title="Permalink to this heading"></a></h3>
<p>To install InfluxDB 2.x., follow the steps at <a class="reference external" href="https://portal.influxdata.com/downloads/">https://portal.influxdata.com/downloads/</a>.</p>
<p>For high throughput networks (5+ Gbps) you will likely want to install InfluxDB to a separate machine or VM from that of the LibreQoS server to avoid CPU load.</p>
<p>Restart your system that is running InfluxDB</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>reboot
</pre></div>
</div>
<p>Check to ensure InfluxDB is running properly. This command should show “Active: active” with green dot.</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>service<span class="w"> </span>influxdb<span class="w"> </span>status
</pre></div>
</div>
<p>Check that Web UI is running:<br></p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>http://SERVER_IP_ADDRESS:8086
</pre></div>
</div>
<p>Create Bucket</p>
<ul class="simple">
<li><p>Data &gt; Buckets &gt; Create Bucket</p></li>
</ul>
<p>Call the bucket “libreqos” (all lowercase, without quotes).<br>
Have it store as many days of data as you prefer. 7 days is standard.&lt;&gt;
Import Dashboard</p>
<ul class="simple">
<li><p>Boards &gt; Create Dashboard &gt; Import Dashboard</p></li>
</ul>
<p>Then upload the file <a class="reference external" href="https://github.com/rchac/LibreQoS/blob/main/src/influxDBdashboardTemplate.json">influxDBdashboardTemplate.json</a> to InfluxDB.</p>
<p><a class="reference external" href="https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/">Generate an InfluxDB Token</a>. It will be added to ispConfig.py in the following steps.</p>
</section>
<section id="modify-ispconfig-py">
<h3>Modify ispConfig.py<a class="headerlink" href="#modify-ispconfig-py" title="Permalink to this heading"></a></h3>
<p>Copy ispConfig.example.py to ispConfig.py and edit as needed</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>/home/<span class="nv">$USER</span>/LibreQoS/src/
cp<span class="w"> </span>ispConfig.example.py<span class="w"> </span>ispConfig.py
nano<span class="w"> </span>ispConfig.py
</pre></div>
</div>
<ul class="simple">
<li><p>Set upstreamBandwidthCapacityDownloadMbps and upstreamBandwidthCapacityUploadMbps to match the bandwidth in Mbps of your network’s upstream / WAN internet connection. The same can be done for generatedPNDownloadMbps and generatedPNUploadMbps.</p></li>
<li><p>Set interfaceA to the interface facing your core router (or bridged internal network if your network is bridged)</p></li>
<li><p>Set interfaceB to the interface facing your edge router</p></li>
<li><p>Set <code class="docutils literal notranslate"><span class="pre">enableActualShellCommands</span> <span class="pre">=</span> <span class="pre">True</span></code> to allow the program to actually run the commands.</p></li>
</ul>
</section>
<section id="integrations">
<h3>Integrations<a class="headerlink" href="#integrations" title="Permalink to this heading"></a></h3>
<p>Integrations now share a common framework thanks to <a class="reference external" href="https://github.com/rchac/LibreQoS/pull/145">this pull</a>. This also allows for graphing the network topology with graphviz.</p>
<section id="uisp-integration">
<h4>UISP Integration<a class="headerlink" href="#uisp-integration" title="Permalink to this heading"></a></h4>
<p>To run the UISP Integration, use</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>python3<span class="w"> </span>integrationUISP.py
</pre></div>
</div>
<p>On the first successful run, it will create a network.json and ShapedDevices.csv file.
If a network.json file exists, it will not be overwritten.
You can modify the network.json file to more accurately reflect bandwidth limits.
ShapedDevices.csv will be overwritten every time the UISP integration is run.
You have the option to run integrationUISP.py automatically on boot and every 30 minutes, which is recommended. This can be enabled by setting <code class="docutils literal notranslate"><span class="pre">automaticImportUISP</span> <span class="pre">=</span> <span class="pre">True</span></code> in ispConfig.py</p>
</section>
</section>
<section id="network-json">
<h3>Network.json<a class="headerlink" href="#network-json" title="Permalink to this heading"></a></h3>
<p>Network.json allows ISP operators to define a Hierarchical Network Topology, or Flat Network Topology.</p>
<p>For networks with no Parent Nodes (no strictly defined Access Points or Sites) edit the network.json to use a Flat Network Topology with
<code class="docutils literal notranslate"><span class="pre">nano</span> <span class="pre">network.json</span></code>
setting the following file content:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{}</span>
</pre></div>
</div>
<p>If you plan to use the built-in UISP or Splynx integrations, you do not need to create a network.json file quite yet.</p>
<p>If you plan to use the built-in UISP integration, it will create this automatically on its first run (assuming network.json is not already present). You can then modify the network.json to more accurately reflect your topology.</p>
<p>If you will not be using an integration, you can manually define the network.json following the template file - network.example.json</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>+-----------------------------------------------------------------------+
| Entire Network |
+-----------------------+-----------------------+-----------------------+
| Parent Node A | Parent Node B | Parent Node C |
+-----------------------+-------+-------+-------+-----------------------+
| Parent Node D | Sub 3 | Sub 4 | Sub 5 | Sub 6 | Sub 7 | Parent Node F |
+-------+-------+-------+-------+-------+-------+-------+-------+-------+
| Sub 1 | Sub 2 | | | | Sub 8 | Sub 9 |
+-------+-------+-------+-----------------------+-------+-------+-------+
</pre></div>
</div>
<section id="manual-editing">
<h4>Manual Editing<a class="headerlink" href="#manual-editing" title="Permalink to this heading"></a></h4>
<ul class="simple">
<li><p>Modify the network.json file using your preferred JSON editor (Geany for example)</p></li>
<li><p>Parent node name must match that used for clients in ShapedDevices.csv</p></li>
</ul>
</section>
</section>
<section id="shapeddevices-csv">
<h3>ShapedDevices.csv<a class="headerlink" href="#shapeddevices-csv" title="Permalink to this heading"></a></h3>
<p>If you are using an integration, this file will be automatically generated. If you are not using an integration, you can manually edit the file.</p>
<ul class="simple">
<li><p>Modify the ShapedDevices.csv file using your preferred spreadsheet editor (LibreOffice Calc, Excel, etc), following the template file - ShapedDevices.example.csv</p></li>
<li><p>An IPv4 address or IPv6 address is required for each entry.</p></li>
<li><p>The Access Point or Site name should be set in the Parent Node field. Parent Node can be left blank for flat networks.</p></li>
<li><p>The ShapedDevices.csv file allows you to set minimum guaranteed, and maximum allowed bandwidth per subscriber.</p></li>
<li><p>The minimum allowed plan rates for Circuits are 2Mbit. Bandwidth min and max should both be above that threshold.</p></li>
<li><p>Recommendation: set the min bandwidth to something like 25/10 and max to 1.15X advertised plan rate by using bandwidthOverheadFactor = 1.15</p>
<ul>
<li><p>This way, when an AP hits its ceiling, users have any remaining AP capacity fairly distributed between them.</p></li>
<li><p>Ensure a reasonable minimum bandwidth minimum for every subscriber, allowing them to utilize up to the maximum provided when AP utilization is below 100%.</p></li>
</ul>
</li>
</ul>
<p>Note regarding SLAs: For customers with SLA contracts that guarantee them a minimum bandwidth, set their plan rate as the minimum bandwidth. That way when an AP approaches its ceiling, SLA customers will always get that amount.</p>
<p><img alt="image" src="https://user-images.githubusercontent.com/22501920/200134960-28709d0f-48fe-4129-b4fd-70b204cade2c.png" /></p>
</section>
</section>
<section id="how-to-run-libreqos">
<h2>How to run LibreQoS<a class="headerlink" href="#how-to-run-libreqos" title="Permalink to this heading"></a></h2>
<section id="one-time-debug-runs">
<h3>One-Time / Debug Runs<a class="headerlink" href="#one-time-debug-runs" title="Permalink to this heading"></a></h3>
<p>One-time runs show the response from the terminal for each filter rule applied, and can be very helpful for debugging and to make sure it is correctly configured.</p>
<ul class="simple">
<li><p>Modify setting parameters in ispConfig.py to suit your environment</p></li>
<li><p>For one-time runs, use</p></li>
</ul>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>./LibreQoS.py
</pre></div>
</div>
<ul class="simple">
<li><p>To use the debug mode with more verbose output, use:</p></li>
</ul>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>./LibreQoS.py<span class="w"> </span>--debug
</pre></div>
</div>
</section>
<section id="running-as-a-service">
<h3>Running as a service<a class="headerlink" href="#running-as-a-service" title="Permalink to this heading"></a></h3>
<p>To run as a service, we create a systemd service to run scheduler.py.
scheduler.py does the following:</p>
<ul class="simple">
<li><p>On start: Run a full setup of queues</p></li>
<li><p>Every 30 minutes: Update queues, pulling new configuration from CRM integration if enabled</p></li>
</ul>
<p>On Linux distributions that use systemd, such as Ubuntu, we create</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>nano<span class="w"> </span>/etc/systemd/system/LibreQoS.service
</pre></div>
</div>
<p>Then paste the text below, replacing “/home/YOUR_USERNAME/LibreQoS” with wherever you downloaded LibreQoS to. Be sure to replace YOUR_USERNAME with your actual username, because otherwise when the root user executes it, it will look in the wrong directory.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[Unit]
After=network.service
[Service]
WorkingDirectory=/home/YOUR_USERNAME/LibreQoS/src
ExecStart=/usr/bin/python3 /home/YOUR_USERNAME/LibreQoS/src/scheduler.py
ExecStopPost=/bin/bash -c &#39;/usr/bin/python3 /home/YOUR_USERNAME/LibreQoS/src/LibreQoS.py --clearrules&#39;
ExecStop=/bin/bash -c &#39;/usr/bin/python3 /home/YOUR_USERNAME/LibreQoS/src/LibreQoS.py --clearrules&#39;
Restart=always
[Install]
WantedBy=default.target
</pre></div>
</div>
<p>Then run</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>chmod<span class="w"> </span><span class="m">664</span><span class="w"> </span>/etc/systemd/system/LibreQoS.service
sudo<span class="w"> </span>systemctl<span class="w"> </span>daemon-reload
sudo<span class="w"> </span>systemctl<span class="w"> </span><span class="nb">enable</span><span class="w"> </span>LibreQoS.service
</pre></div>
</div>
<p>You can start the service using</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>systemctl<span class="w"> </span>start<span class="w"> </span>LibreQoS.service
</pre></div>
</div>
<p>You can check the status of the service using</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>systemctl<span class="w"> </span>status<span class="w"> </span>LibreQoS.service
</pre></div>
</div>
<p>You can restart the service to refresh any changes you’ve made to the ShapedDevices.csv file by doing</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>systemctl<span class="w"> </span>restart<span class="w"> </span>LibreQoS.service
</pre></div>
</div>
<p>You can also stop the service to remove all queues and IP rules by doing</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>systemctl<span class="w"> </span>stop<span class="w"> </span>LibreQoS.service
</pre></div>
</div>
</section>
<section id="crontab">
<h3>Crontab<a class="headerlink" href="#crontab" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>At 4AM: Runs a full reload of all queues to make sure they perfectly match queueStructure.py and that any changes to network.json can be applied.</p></li>
</ul>
<p>First, check to make sure the cron job does not already exist.</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>crontab<span class="w"> </span>-l<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>-q<span class="w"> </span><span class="s1">&#39;LibreQoS&#39;</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s1">&#39;entry exists&#39;</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s1">&#39;entry does not exist&#39;</span>
</pre></div>
</div>
<p>The above should output “entry does not exist”. If so, proceed to add it with:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="o">(</span>sudo<span class="w"> </span>crontab<span class="w"> </span>-l<span class="w"> </span><span class="m">2</span>&gt;/dev/null<span class="p">;</span><span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s2">&quot;0 4 * * * /bin/systemctl try-restart LibreQoS&quot;</span><span class="o">)</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>sudo<span class="w"> </span>crontab<span class="w"> </span>-
sudo<span class="w"> </span>/etc/init.d/cron<span class="w"> </span>start
</pre></div>
</div>
</section>
</section>
<section id="common-issues">
<h2>Common Issues<a class="headerlink" href="#common-issues" title="Permalink to this heading"></a></h2>
<section id="program-running-but-traffic-not-shaping">
<h3>Program Running, But Traffic Not Shaping<a class="headerlink" href="#program-running-but-traffic-not-shaping" title="Permalink to this heading"></a></h3>
<p>In ispConfig.py, make sure the edge and core interfaces correspond to correctly to the edge and core. Try swapping the interfaces to see if shaping starts to work.</p>
</section>
<section id="rtnetlink-answers-invalid-argument">
<h3>RTNETLINK answers: Invalid argument<a class="headerlink" href="#rtnetlink-answers-invalid-argument" title="Permalink to this heading"></a></h3>
<p>This tends to show up when the MQ qdisc cannot be added correctly to the NIC interface. This would suggest the NIC has insufficient RX/TX queues. Please make sure you are using the <a class="reference internal" href="#network-interface-card"><span class="xref myst">recommended NICs</span></a>.</p>
</section>
</section>
<section id="performance-tuning">
<h2>Performance Tuning<a class="headerlink" href="#performance-tuning" title="Permalink to this heading"></a></h2>
<section id="ospf">
<h3>OSPF<a class="headerlink" href="#ospf" title="Permalink to this heading"></a></h3>
<p>It is recommended to set the OSPF timers of both OSPF neighbors (core and edge router) to minimize downtime upon a reboot of the LibreQoS server.</p>
<ul class="simple">
<li><p>hello interval</p></li>
<li><p>dead</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../TechnicalDocs/performance-tuning.html" class="btn btn-neutral float-left" title="Performance Tuning" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023, LibreQoE.</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