===============
Traffic Control
===============

.. sidebar:: Contents

  .. contents::
      :depth: 3
      :local:


This chapter covers some aspects related to ``traffic control``,
which is the core element to configure Quality of Service (QoS).

In order to process network traffic, three different objects can
be combined: **qdiscs**, **classes** and **filters**:

 * A **qdisc** (``traffic control`` on OSDx) is a traffic scheduler.
   E.g., FIFO (*first-in first-out*) is a common example of Qdisc.
 * Some qdiscs can contain **classes**, which can be seen as
   containers for further Qdiscs. These are called classful qdiscs. These
   objects are very useful because network traffic can be prioritized by
   specifying the classes that should be dequeued first.
 * **Filters** (``match`` on OSDx) can be used to determine in
   which class a packet will be queued. They are always attached
   to classes.


Configuration
=============

The following types of ``traffic control`` are currently supported:

   * **fifo**: the simplest traffic control. Pure first-in,
     first-out behavior. It can be limited in both packets and
     bytes.
     This is a classless qdisc.
   * **fq-codel**: *fair queuing controlled delay* uses a stochastic
     model to classify incoming packets into different flows.
     This traffic control provides a fair share of the bandwidth
     to every flow.
     This is a classless qdisc.
   * **network-emulator**: this traffic control can be used to add
     or modify some network characteristics, such as delay, packet
     loss, duplication, etc.
     This is a classless qdisc.
   * **tbf**: *token bucket filter* is suited for slowing traffic
     down to a precisely configured rate. A different ``traffic control``
     can be specified as a TBF child.
     This is a classless qdisc.
   * **htb**: *hierarchy token bucket* implements a rich linksharing
     hierarchy of classes. HTB can prioritize classes and each class can
     contain ``traffic control`` as a child.
     This is a classful qdisc.
   * **wfq**: *weighted fair queuing* is a network-scheduling algorithm that
     allows users to specify what fraction of the total capacity is given to each
     class, depending on their ``weight`` value.
     This qdisc can be offloaded to hardware on some devices, provided that the
     Ethernet port used is not part of the router's switch, if the router is equipped with one.
     If hardware offload is not enabled, *htb* is used internally.
     This is a classful qdisc.
   * **mqprio**: *multiqueue priority qdisc* is a hardware-offloaded
     queueing discipline designed for modern network interface cards that
     support multiple transmit queues. MQPRIO provides traffic class-based
     scheduling with per-class bandwidth rate limiting.
     Unlike other classful qdiscs, mqprio does not support traditional
     ``match`` filters. Traffic classification must be performed externally
     using ``traffic policies`` with the ``set class`` action.
     This is a classful qdisc.


This is the syntax to create a ``traffic control``:

.. code-block:: none

  set traffic control <qdisc_name> type <qdisc_type> [ ... ]

A ``traffic control`` discipline can be assigned to an interface.
There are two modes: ingress and egress. The former one is used to
control inbound traffic (in) and the latter to control outbound traffic
(out).

In order to assign a ``traffic control`` to an interface, you have to use
the following command:

.. code-block:: none

  set interfaces <if_type> <if_name> traffic control <in / out> <qdisc_name>


.. tip::

   When it comes to testing bandwidth, the ``monitor test performance``
   operational command proves to be very handy.


Examples
========

Prioritizing traffic
--------------------

Let's suppose we want to set up a ``traffic control`` discipline in the egress
hook of our ``eth0``.

We want the following features:

  * Device bandwidth will be limited to 10 Mbps.
  * Three priority levels that will be mapped to three different queues: gold
    queue (high priority, traffic with mark 99), silver queue (medium priority,
    vrfs SRV1 or SRV2) and bronze queue (low priority, unmatched traffic).
  * The gold queue will have an assured bandwidth of 50%; the silver queue 30%;
    and the bronze one 20%.
  * Any remaining bandwidth will be distributed amongst all queues.

In OSDx, we can achieve that by configuring the following commands:

.. code-block:: none

  set traffic control QoS type htb bandwidth 10
  set traffic control QoS type htb class 1 bandwidth percentage 50
  set traffic control QoS type htb class 1 priority 1
  set traffic control QoS type htb class 2 bandwidth percentage 30
  set traffic control QoS type htb class 2 priority 4
  set traffic control QoS type htb class 3 bandwidth percentage 20
  set traffic control QoS type htb class 3 priority 7
  set traffic control QoS type htb match 1 class 1
  set traffic control QoS type htb match 1 mark 99
  set traffic control QoS type htb match 1 set tos 8
  set traffic control QoS type htb match 2 class 2
  set traffic control QoS type htb match 2 vrf-mark SRV1
  set traffic control QoS type htb match 3 class 2
  set traffic control QoS type htb match 3 vrf-mark SRV2
  set traffic control QoS type htb default-class 3

Finally, to attach this traffic control to ``eth0``, you have to use this command:

.. code-block:: none

  set interfaces ethernet eth0 traffic control out QoS

Limiting interface throughput
-----------------------------

Now, let's suppose we want to limit inbound traffic in ``eth1`` to 512 Kbps.
This can be easily done using a TBF ``traffic control``.

In this case, we will configure a bucket size of 1875 bytes (0.015 mbit),
this parameter should always be higher than the device mtu.

To create the ``traffic control`` discipline, type the following commands:

.. code-block:: none

  set traffic control LIMITER type tbf bandwidth 0.512
  set traffic control LIMITER type tbf burst 0.015
  set traffic control LIMITER type tbf latency 1
  set interfaces ethernet eth1 traffic control in LIMITER


In the case of TBF ``traffic control``, we could also specify a child qdisc.

*Example:*

.. code-block:: none

  set traffic control FQ_LEAF type fq-codel
  set traffic control LIMITER type tbf child-control FQ_LEAF


Hardware-offloaded multiqueue scheduling
-----------------------------------------

The **mqprio** qdisc provides hardware-offloaded traffic management for
interfaces that support multiple transmit queues. Unlike software-based
qdiscs, mqprio delegates traffic scheduling to the network interface hardware.

Let's configure ``eth0`` with four traffic classes for different service levels:
voice (high priority), gold (premium data), silver (standard data), and a
default class for best-effort traffic.

We'll allocate 2.5 Gbps maximum bandwidth to each service class:

.. code-block:: none

  set traffic control ETHWAN_QOS type mqprio class 1 bandwidth rate 2500
  set traffic control ETHWAN_QOS type mqprio class 1 description "VOICE"
  set traffic control ETHWAN_QOS type mqprio class 2 bandwidth rate 2500
  set traffic control ETHWAN_QOS type mqprio class 2 description "GOLD"
  set traffic control ETHWAN_QOS type mqprio class 3 bandwidth rate 2500
  set traffic control ETHWAN_QOS type mqprio class 3 description "SILVER"
  set traffic control ETHWAN_QOS type mqprio class 4 description "DEFAULT"
  set traffic control ETHWAN_QOS type mqprio default-class 4

.. note::

   Bandwidth rate in **mqprio** qdiscs is configured internally in 50 Mbps steps.
   This means that values that are not multiple of 50 Mbps will be rounded down
   to the nearest multiple of 50 Mbps.

Attach the qdisc to the interface:

.. code-block:: none

  set interfaces ethernet eth0 traffic control out ETHWAN_QOS

Since mqprio does not support ``match`` filters, we must use ``traffic policies``
to classify packets into the appropriate classes. Create a policy that assigns
voice traffic (UDP port 5060) to class 1, and premium customers (specific IP range)
to class 2:

.. code-block:: none

  set traffic policy CLASSIFIER rule 10 selector VOICE
  set traffic policy CLASSIFIER rule 10 set class 1
  set traffic policy CLASSIFIER rule 20 selector GOLD
  set traffic policy CLASSIFIER rule 20 set class 2
  set traffic selector VOICE rule 10 protocol udp
  set traffic selector VOICE rule 10 destination port 5060
  set traffic selector GOLD rule 10 source address 10.100.0.0/24

Apply the traffic policies to the interface:

.. code-block:: none

  set interfaces ethernet eth0 traffic policy link-out CLASSIFIER

All unclassified traffic will be handled by the default class (class 4).

.. note::

   **mqprio** is only available on interfaces with hardware multiqueue support
   and can only be configured in egress (out) mode.


:ref:`Here <example_traffic_control_trafficcontrol>`, you can find more
examples related to ``traffic control`` disciplines.


Advanced features
=================

Combining ``traffic policies`` and ``traffic control``
disciplines could prove very useful in some situations. Although there are many filters that can be
used in a ``traffic control`` to classify network traffic (e.g., mark, TOS, etc),
in some situations you may need to use more specialized ACLs (or
``traffic selectors``).

Network packets can be marked using ``traffic policies`` and, depending on this
value, queue packets in a specific ``traffic control`` class.
For **mqprio** this is mandatory, since it does not support ``match``.

In addition to this, if we just need to limit traffic, we can use ``traffic
policy`` action ``rate-limit``.

*Example:*

.. code-block:: none

  set traffic policy LIMITER rule 1 action rate-limit <rate> [burst <burst>]

The ``traffic policy`` will drop any packets that exceed the rate-limit.

:doc:`Here <../policy/index>` you can find more information about ``traffic policies``.


Monitoring
==========

The :osdx:op:`traffic control show` operational command can be used to
display statistics related to ``traffic control`` disciplines.

*Example:*

.. code-block:: none

  admin@osdx$ traffic control show
  Traffic control for interface 'eth1' - 'ingress' mode

  ---------------------------------------------------------------------------
  ID   traffic control    type    parent  bytes sent  pkts sent  pkts dropped
  ---------------------------------------------------------------------------
  1:0  LIMITER          tbf       root        647202       9805          2369
  2:0  FQ_LEAF          fq_codel  1:1         647202       9805          2369

  Traffic control for interface 'eth0' - 'egress' mode

  ------------------------------------------------------------------------------------
  ID   traffic control        type         parent  bytes sent  pkts sent  pkts dropped
  ------------------------------------------------------------------------------------
  1:0  QoS              htb                root          1320         13             0
  1:1  QoS              class 1            1:0            220          2             0
  1:2  QoS              class 2            1:0            430          3             0
  1:3  QoS              class 3 (default)  1:0            670          8             0


Command Summary
===============

..
  depth=3 to show traffic control types

.. osdx:cmdtree:: cfg
  :maxdepth: 3

  traffic control

.. osdx:cmdtree:: op

  traffic control