===============
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 enqueued. They are always attached
   to classes.


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

Currently, the following types of ``traffic control`` are 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 all the flows.
     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 child for TBF.
     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 a ``traffic control`` as a child.
     This is a classful qdisc.
   * **wfq**: *weighted fair queuing* is a network scheduling algorithm that
     allows specifying which 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.


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 turns out 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 levels of priority 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%.
  * If there's remaining bandwidth, it will be distributed among all queues.

On 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 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


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


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

It could be very useful to combine ``traffic policies`` and ``traffic control``
disciplines 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 it may happen that you need to use more specialized ACLs (or
``traffic selectors``).

Network packets can be marked using ``traffic policies`` and, depending on this
value, enqueue packets in a specific ``traffic control`` class.

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

*Example:*

.. code-block:: none

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

That ``traffic policy`` will drop those packets that go over the rate-limit.

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


Monitoring
==========

The operational command :osdx:op:`traffic control show` 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