===============
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 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.
   * **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.
   * **network-emulator**: this traffic control can be used to add
     or modify some network characteristics, such as delay, packet
     loss, duplication, etc.
   * **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.
   * **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 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 tc` 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