diff options
27 files changed, 1071 insertions, 1084 deletions
diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.png b/docs/_static/images/dhcp-relay-through-gre-bridge.png Binary files differnew file mode 100644 index 00000000..1f3e7744 --- /dev/null +++ b/docs/_static/images/dhcp-relay-through-gre-bridge.png diff --git a/docs/_static/images/gns3-01.png b/docs/_static/images/gns3-01.png Binary files differnew file mode 100644 index 00000000..a655d6aa --- /dev/null +++ b/docs/_static/images/gns3-01.png diff --git a/docs/_static/images/gns3-02.png b/docs/_static/images/gns3-02.png Binary files differnew file mode 100644 index 00000000..3dffdd2b --- /dev/null +++ b/docs/_static/images/gns3-02.png diff --git a/docs/_static/images/gns3-03.png b/docs/_static/images/gns3-03.png Binary files differnew file mode 100644 index 00000000..fcab6c5d --- /dev/null +++ b/docs/_static/images/gns3-03.png diff --git a/docs/_static/images/gns3-04.png b/docs/_static/images/gns3-04.png Binary files differnew file mode 100644 index 00000000..afc30131 --- /dev/null +++ b/docs/_static/images/gns3-04.png diff --git a/docs/_static/images/gns3-05.png b/docs/_static/images/gns3-05.png Binary files differnew file mode 100644 index 00000000..fee0dc65 --- /dev/null +++ b/docs/_static/images/gns3-05.png diff --git a/docs/_static/images/gns3-06.png b/docs/_static/images/gns3-06.png Binary files differnew file mode 100644 index 00000000..c03cd89f --- /dev/null +++ b/docs/_static/images/gns3-06.png diff --git a/docs/_static/images/gns3-07.png b/docs/_static/images/gns3-07.png Binary files differnew file mode 100644 index 00000000..89d0a565 --- /dev/null +++ b/docs/_static/images/gns3-07.png diff --git a/docs/_static/images/gns3-08.png b/docs/_static/images/gns3-08.png Binary files differnew file mode 100644 index 00000000..aca0ff8a --- /dev/null +++ b/docs/_static/images/gns3-08.png diff --git a/docs/_static/images/gns3-09.png b/docs/_static/images/gns3-09.png Binary files differnew file mode 100644 index 00000000..7ae38c30 --- /dev/null +++ b/docs/_static/images/gns3-09.png diff --git a/docs/_static/images/gns3-10.png b/docs/_static/images/gns3-10.png Binary files differnew file mode 100644 index 00000000..1ee70d58 --- /dev/null +++ b/docs/_static/images/gns3-10.png diff --git a/docs/_static/images/gns3-11.png b/docs/_static/images/gns3-11.png Binary files differnew file mode 100644 index 00000000..7990c73a --- /dev/null +++ b/docs/_static/images/gns3-11.png diff --git a/docs/_static/images/gns3-12.png b/docs/_static/images/gns3-12.png Binary files differnew file mode 100644 index 00000000..9ad51f70 --- /dev/null +++ b/docs/_static/images/gns3-12.png diff --git a/docs/_static/images/gns3-13.png b/docs/_static/images/gns3-13.png Binary files differnew file mode 100644 index 00000000..5f9dd783 --- /dev/null +++ b/docs/_static/images/gns3-13.png diff --git a/docs/_static/images/gns3-14.png b/docs/_static/images/gns3-14.png Binary files differnew file mode 100644 index 00000000..447fcafe --- /dev/null +++ b/docs/_static/images/gns3-14.png diff --git a/docs/_static/images/gns3-15.png b/docs/_static/images/gns3-15.png Binary files differnew file mode 100644 index 00000000..956b9edb --- /dev/null +++ b/docs/_static/images/gns3-15.png diff --git a/docs/_static/images/gns3-16.png b/docs/_static/images/gns3-16.png Binary files differnew file mode 100644 index 00000000..4f75ffab --- /dev/null +++ b/docs/_static/images/gns3-16.png diff --git a/docs/_static/images/gns3-17.png b/docs/_static/images/gns3-17.png Binary files differnew file mode 100644 index 00000000..64eff002 --- /dev/null +++ b/docs/_static/images/gns3-17.png diff --git a/docs/_static/images/gns3-20.png b/docs/_static/images/gns3-20.png Binary files differnew file mode 100644 index 00000000..17d92dea --- /dev/null +++ b/docs/_static/images/gns3-20.png diff --git a/docs/_static/images/gns3-21.png b/docs/_static/images/gns3-21.png Binary files differnew file mode 100644 index 00000000..e461016a --- /dev/null +++ b/docs/_static/images/gns3-21.png diff --git a/docs/_static/images/gns3-215.png b/docs/_static/images/gns3-215.png Binary files differnew file mode 100644 index 00000000..fde268ba --- /dev/null +++ b/docs/_static/images/gns3-215.png diff --git a/docs/_static/images/gns3-22.png b/docs/_static/images/gns3-22.png Binary files differnew file mode 100644 index 00000000..6ed52c1d --- /dev/null +++ b/docs/_static/images/gns3-22.png diff --git a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst b/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst new file mode 100644 index 00000000..f94eb67f --- /dev/null +++ b/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst @@ -0,0 +1,77 @@ +.. _examples-dhcp-relay-through-gre-bridge: + + +DHCP Relay through GRE-Bridge +----------------------------- + +Diagram +^^^^^^^ + +.. image:: /_static/images/dhcp-relay-through-gre-bridge.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +Configuration +^^^^^^^^^^^^^ + +DHCP Server +""""""""""" + +.. code-block:: none + + set interfaces ethernet eth0 address '10.0.2.1/24' + set interfaces loopback lo address '3.3.3.3/24' + set interfaces tunnel tun100 address '172.16.0.2/30' + set interfaces tunnel tun100 encapsulation 'gre-bridge' + set interfaces tunnel tun100 local-ip '10.0.2.1' + set interfaces tunnel tun100 remote-ip '192.168.0.1' + set protocols ospf area 0 network '3.3.3.0/24' + set protocols ospf area 0 network '10.0.2.0/24' + set protocols ospf parameters router-id '3.3.3.3' + set protocols static interface-route 10.0.1.2/32 next-hop-interface tun100 + set service dhcp-server shared-network-name asdf authoritative + set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 start '3.3.3.30' + set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 stop '3.3.3.40' + set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 default-router '10.0.1.2' + set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 start '10.0.1.200' + set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 stop '10.0.1.210' + set service dhcp-server shared-network-name asdf subnet 10.2.1.0/24 range 0 start '10.2.1.222' + set service dhcp-server shared-network-name asdf subnet 10.2.1.0/24 range 0 stop '10.2.1.233' + set service dhcp-server shared-network-name asdf subnet 172.16.0.0/30 range 0 start '172.16.0.1' + set service dhcp-server shared-network-name asdf subnet 172.16.0.0/30 range 0 stop '172.16.0.2' + + +In-Between Router +""""""""""""""""" + +.. code-block:: none + + set interfaces ethernet eth0 address '192.168.0.2/24' + set interfaces ethernet eth1 address '10.0.2.2/24' + set protocols ospf area 0 network '192.168.0.0/24' + set protocols ospf area 0 network '10.0.2.0/24' + set protocols ospf parameters router-id '192.168.0.2' + + +DHCP Relay +"""""""""" + +.. code-block:: none + + set interfaces ethernet eth0 address '10.0.1.2/24' + set interfaces ethernet eth1 address '192.168.0.1/24' + set interfaces loopback lo address '1.1.1.1' + set interfaces tunnel tun100 address '172.16.0.1/30' + set interfaces tunnel tun100 encapsulation 'gre-bridge' + set interfaces tunnel tun100 local-ip '192.168.0.1' + set interfaces tunnel tun100 remote-ip '10.0.2.1' + set protocols ospf area 0 network '10.0.1.0/24' + set protocols ospf area 0 network '192.168.0.0/24' + set protocols ospf area 0 network '1.1.1.0/24' + set protocols ospf parameters router-id '1.1.1.1' + set protocols static interface-route 3.3.3.3/32 next-hop-interface tun100 + set service dhcp-relay interface 'eth0' + set service dhcp-relay interface 'tun100' + set service dhcp-relay server '3.3.3.3' + diff --git a/docs/appendix/examples/index.rst b/docs/appendix/examples/index.rst index 0f4ba595..0f340872 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/appendix/examples/index.rst @@ -16,3 +16,4 @@ This chapter contains various configuration Examples azure-vpn-bgp azure-vpn-dual-bgp tunnelbroker-ipv6 + dhcp-relay-through-gre-bridge diff --git a/docs/appendix/vyos-on-gns3.rst b/docs/appendix/vyos-on-gns3.rst new file mode 100644 index 00000000..f17715b2 --- /dev/null +++ b/docs/appendix/vyos-on-gns3.rst @@ -0,0 +1,175 @@ +.. _vyos-on-gns3: + +VyOS on GNS3 +############ + +Sometimes you may want to test VyOS in a lab environment. +`GNS3 <http://www.gns3.com>`__ is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +Requirements +------------ + +The following items are required: + +* A VyOS installation image (.iso file). + `Here <https://docs.vyos.io/en/latest/install.html#download>`__ you + can find how to get it. + +* A working GNS3 installation. For further information see the + `GNS3 documentation <https://docs.gns3.com/>`__. + +.. _vm_setup: + +VM setup +-------- + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +.. figure:: /_static/images/gns3-01.png + +Select **Quemu VMs** and then click on the ``New`` button. + +.. figure:: /_static/images/gns3-02.png + +Write a name for your VM, for instance "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.png + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.png + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.png + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.png + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.png + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.png + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.png + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.png + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the ``Edit`` button. + +.. figure:: /_static/images/gns3-11.png + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +* Click on the ``Browse...`` button to choose the **Symbol** you want to + have representing your VM. +* In **Category** select in which group you want to find your VM. +* Set the **Boot priority** to **CD/DVD-ROM**. + +.. figure:: /_static/images/gns3-12.png + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.png + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.png + +.. note:: You probably will want to accept to copy the .iso file to your + default image directory when you are asked. + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +.. figure:: /_static/images/gns3-15.png + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click ``OK``, which will save and close the **QEMU VM template +configuration** window. + +.. figure:: /_static/images/gns3-16.png + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.png + + +.. _vyos_installation: + +VyOS installation +----------------- + +* Create a new project. +* Drag the newly created VyOS VM into it. +* Start the VM. +* Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +* `Install VyOS <https://docs.vyos.io/en/latest/install.html#install>`__ + as normal (that is, using the ``install image`` command). + +* After a successful installation, shutdown the VM with the ``poweroff`` + command. + +* **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +.. _vyos_vm_configuration: + +VyOS VM configuration +--------------------- + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +.. figure:: /_static/images/gns3-20.png + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +.. figure:: /_static/images/gns3-21.png + +Set the number of required network adapters, for example **4**. + +.. figure:: /_static/images/gns3-215.png + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.png + +The VyOS VM is now ready to be deployed. + diff --git a/docs/index.rst b/docs/index.rst index ded1a6b4..a18c2720 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,6 +65,7 @@ Appendix appendix/examples/index appendix/commandtree/index appendix/vyos-on-vmware + appendix/vyos-on-gns3 appendix/vyos-on-baremetal appendix/migrate-from-vyatta diff --git a/docs/qos.rst b/docs/qos.rst index 7980cffb..51ed0893 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -1,1416 +1,1149 @@ .. _qos: -QoS and Traffic Policy -====================== - -VyOS uses tc_ as backend for QoS. VyOS provides its users with configuration -nodes for the following shaping/queueing/policing disciplines: - -* HTB -* HFSC -* SFQ -* pfifo -* network-emulator -* PRIO -* GRED -* TBF -* DRR - -Configuration nodes -------------------- - -VyOS QoS configuration is done in two steps. The first one consists in setting -up your classes/queues and traffic filters to distribute traffic amongst them. -The second step is to apply such traffic policy to an interface ingress or -egress. - -Creating a traffic policy -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Such configuration takes place under the `traffic-policy` tree. - -Available subtrees : - -.. code-block:: none - - set traffic-policy drop-tail NAME - set traffic-policy fair-queue NAME - set traffic-policy limiter NAME - set traffic-policy network-emulator NAME - set traffic-policy priority-queue NAME - set traffic-policy random-detect NAME - set traffic-policy rate-control NAME - set traffic-policy round-robin NAME - set traffic-policy shaper NAME - set traffic-policy shaper-hfsc NAME - -Apply traffic policy to an interface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Once a traffic-policy is created, you can apply it to an interface : - -.. code-block:: none - - set interfaces ethernet eth0 traffic-policy in WAN-IN - set interfaces etherhet eth0 traffic-policy out WAN-OUT - -A Real-World Example -^^^^^^^^^^^^^^^^^^^^ - -This policy sets download and upload bandwidth maximums (roughly 90% of the speeds possible), then divvies -up the traffic into buckets of importance, giving guaranteed bandwidth chunks to types of -traffic that are necessary for general interactive internet use, like web browsing, streaming, or gaming. - -After identifying and prioritizing that traffic, it drops the remaining traffic into a general-priority -bucket, which it gives a lower priority than what is required for real-time use. If there is no real-time -traffic that needs the bandwidth, the lower-priority traffic can use most of the connection. This ensures -that the connection can be used fully by whatever wants it, without suffocating real-time traffic or -throttling background traffic too much. - -.. code-block:: none - - set traffic-policy shaper download bandwidth '175mbit' - set traffic-policy shaper download class 10 bandwidth '10%' - set traffic-policy shaper download class 10 burst '15k' - set traffic-policy shaper download class 10 ceiling '100%' - set traffic-policy shaper download class 10 match dns ip source port '53' - set traffic-policy shaper download class 10 match icmp ip protocol 'icmp' - set traffic-policy shaper download class 10 match ssh ip source port '22' - set traffic-policy shaper download class 10 priority '5' - set traffic-policy shaper download class 10 queue-type 'fair-queue' - set traffic-policy shaper download class 20 bandwidth '10%' - set traffic-policy shaper download class 20 burst '15k' - set traffic-policy shaper download class 20 ceiling '100%' - set traffic-policy shaper download class 20 match http ip source port '80' - set traffic-policy shaper download class 20 match https ip source port '443' - set traffic-policy shaper download class 20 priority '4' - set traffic-policy shaper download class 20 queue-type 'fair-queue' - set traffic-policy shaper download default bandwidth '70%' - set traffic-policy shaper download default burst '15k' - set traffic-policy shaper download default ceiling '100%' - set traffic-policy shaper download default priority '3' - set traffic-policy shaper download default queue-type 'fair-queue' - set traffic-policy shaper upload bandwidth '18mbit' - set traffic-policy shaper upload class 2 bandwidth '10%' - set traffic-policy shaper upload class 2 burst '15k' - set traffic-policy shaper upload class 2 ceiling '100%' - set traffic-policy shaper upload class 2 match ack ip tcp ack - set traffic-policy shaper upload class 2 match dns ip destination port '53' - set traffic-policy shaper upload class 2 match icmp ip protocol 'icmp' - set traffic-policy shaper upload class 2 match ssh ip destination port '22' - set traffic-policy shaper upload class 2 match syn ip tcp syn - set traffic-policy shaper upload class 2 priority '5' - set traffic-policy shaper upload class 2 queue-limit '16' - set traffic-policy shaper upload class 2 queue-type 'fair-queue' - set traffic-policy shaper upload class 5 bandwidth '10%' - set traffic-policy shaper upload class 5 burst '15k' - set traffic-policy shaper upload class 5 ceiling '100%' - set traffic-policy shaper upload class 5 match http ip destination port '80' - set traffic-policy shaper upload class 5 match https ip destination port '443' - set traffic-policy shaper upload class 5 priority '4' - set traffic-policy shaper upload class 5 queue-type 'fair-queue' - set traffic-policy shaper upload default bandwidth '60%' - set traffic-policy shaper upload default burst '15k' - set traffic-policy shaper upload default ceiling '100%' - set traffic-policy shaper upload default priority '3' - set traffic-policy shaper upload default queue-type 'fair-queue' - - -Traffic policies in VyOS ------------------------- -An overview of QoS traffic policies supported by VyOS. - -Drop-tail (FIFO) -^^^^^^^^^^^^^^^^ - -A packet queuing mechanism on a FIFO (First In, First Out) basis; packets are -sent out in the same order as they arrive. The queue has a defined length, -packets arriving after the queue is filled up will be dropped (hence the name -`drop tail`, the "tail" of the queue will be dropped). With this policy in -place, all traffic is treated equally and put into a single queue. Applicable -to outbound traffic only. - -Available commands: - -* Define a drop-tail policy (unique name, exclusive to this policy): - - :code:`set traffic-policy drop-tail <policy name>` - -* Add a description: - - :code:`set traffic-policy drop-tail <policy name> description <description>` - -* Set the queue length limit (max. number of packets in queue), range - 0...4294967295 packets: - - :code:`set traffic-policy drop-tail <policy name> queue-limit <limit>` - -Fair queue (SFQ) -^^^^^^^^^^^^^^^^ - -Fair queue is a packet queuing mechanism that separates traffic flows based on -their source/destination IP addresses and/or source port and places them into -buckets. Bandwidth is allocated fairly between buckets based on the Stochastic -airness Queuing algorithm. Applicable to outbound traffic only. - -Available commands: - -* Define a fair queue policy: - - :code:`set traffic-policy fair-queue <policy name>` - -* Add a description: - - :code:`set traffic-policy fair-queue <policy name> description <description>` - -* Set hash update interval; the algorithm used is stochastic and thus not - 'truly' fair, hash collisions can occur, in which case traffic flows may be - put into the same bucket. To mitigate this, the hashes can be updated at a - set interval, Range 0...4294967295 seconds: - - :code:`set traffic-policy fair-queue <policy name> hash-interval <seconds>` - -* Set the queue-limit (max. number of packets in queue), range 0...4294967295 - packets, default 127: - - :code:`set traffic-policy fair-queue <policy name> queue-limit <limit>` - -Limiter -^^^^^^^ - -The limiter performs ingress policing of traffic flows. Multiple classes of -traffic can be defined and traffic limits can be applied to each class. Traffic -exceeding the defined bandwidth limits is dropped. Applicable to inbound -traffic only. - -Available commands: - -* Define a traffic limiter policy: - :code:`set traffic-policy limiter <policy-name>` -* Add a description: - :code:`set traffic-policy limiter <policy-name> description <description>` - -Traffic classes -*************** - -* Define a traffic class for a limiter policy, range for class ID is 1...4095: - - :code:`set traffic-policy limiter <policy-name> class <class ID>` - -* Add a class description: - - :code:`set traffic-policy limiter <policy-name> class <class ID> description - <description>` - -* Specify a bandwidth limit for a class, in kbit/s: - - :code:`set traffic-policy limiter <policy-name> class <class ID> bandwidth - <rate>`. - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size for a class, the maximum amount of traffic that can be sent, - in bytes: - - :code:`set traffic-policy limiter <policy-name> class <class ID> - burst <burst-size>`. - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -Default class -############# - -* Define a default class for a limiter policy that applies to traffic not - matching any other classes for this policy: - - :code:`set traffic-policy limiter <policy name> default` - -* Specify a bandwidth limit for the default class, in kbit/s: - - :code:`set traffic-policy limiter <policy name> default bandwidth <rate>`. - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size for the default class, the maximum amount of traffic that - can be sent, in bytes: - - :code:`set traffic-policy limiter <policy-name> default burst <burst-size>`. - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -* Specify the priority of the default class to set the order in which the rules - are evaluated, the higher the number the lower the priority, range 0...20 - (default 20): - - :code:`set traffic-policy limiter <policy name> default priority <priority>` - -Matching rules -************** - -* Define a traffic class matching rule: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name>` - -* Add a description: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> description <description>` - -* Specify the priority of a matching rule to set the order in which the rules - are evaluated, the higher the number the lower the priority, range 0...20 - (default 20): - - :code:`set traffic-policy limiter <policy name> class <class ID> - priority <priority>` - -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ether destination <MAC address>` - -* Specify a match criterion based on a **source MAC address** (format: - xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ether source <MAC address>` - -* Specify a match criterion based on **packet type/protocol**, range 0...65535: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ether protocol <number>` - -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> mark <fwmark>` - -* Specify a match criterion based on **VLAN ID**, range 1...4096: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> vif <VLAN ID>` - -**IPv4** - -* Specify a match criterion based on **destination IPv4 address** and/or port, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter <policy name> class <class ID> - match <match name> ip destination <IPv4 address|port>` - -* Specify a match criterion based on **source IPv4 address** and/or port, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter <policy name> class <class ID> - match <match name> ip source <IPv4 address|port>` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` - -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ip protocol <proto>` - -**IPv6** - -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ipv6 destination <IPv6 address|port>` - -* Specify a match criterion based on **source IPv6 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ipv6 source <IPv6 address|port>` - -* Specify a match criterion based on **DSCP (Differentiated Services Code - Point) value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ipv6 dscp <DSCP value>` - -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` - -Network emulator -^^^^^^^^^^^^^^^^ - -The network emulator policy emulates WAN traffic, which is useful for testing -purposes. Applicable to outbound traffic only. - -Available commands: - -* Define a network emulator policy: - - :code:`set traffic-policy network-emulator <policy name>` - -* Add a description: - - :code:`set traffic-policy network-emulator <policy name> description <description>` - -* Specify a bandwidth limit in kbit/s: - - :code:`set traffic-policy network-emulator <policy name> bandwidth <rate>` - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size, the maximum amount of traffic that can be sent, in bytes: - - :code:`set traffic-policy network-emulator <policy name> burst <burst size>` - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -* Define a delay between packets: - - :code:`set traffic-policy network-emulator <policy name> network-delay <delay>` - - Available suffixes: - - * secs (seconds) - * ms (milliseconds, default) - * us (microseconds) - -* Set a percentage of corrupted of packets (one bit flip, unchanged checksum): - - :code:`set traffic-policy network-emulator <policy name> packet-corruption - <percent>` - -* Set a percentage of random packet loss: - - :code:`set traffic-policy network-emulator <policy name> packet-loss <percent>` - -* Set a percentage of packets for random reordering: - - :code:`set traffic-policy network-emulator <policy name> packet-reordering - <percent>` - -* Set a queue length limit in packets, range 0...4294967295, default 127: - - :code:`set traffic-policy network-emulator <policy name> queue-limit <limit>` - -Priority queue -^^^^^^^^^^^^^^ - -Up to seven queues with differing priorities can be defined, packets are placed -into queues based on associated match criteria. Packets are transmitted from -the queues in priority order. If queues with a higher order are being filled -with packets continuously, packets from lower priority queues will only be -transmitted after traffic volume from higher priority queues decreases. - -Available commands: - -* Define a priority queue: - - :code:`set traffic-policy priority-queue <policy name>` - -* Add a description: - - :code:`set traffic-policy priority-queue <policy name> description <description>` - -Traffic classes -*************** - -* Define a traffic class, each class is a separate queue, range for class ID - is 1...7, while 1 being the lowest priority: - - :code:`set traffic-policy priority-queue <policy name> class <class ID>` +*** +QoS +*** -* Add a class description: +The generic name of Quality of Service or Traffic Control involves +things like shaping traffic, scheduling or dropping packets, which +are the kind of things you may want to play with when you have, for +instance, a bandwidth bottleneck in a link and you want to somehow +prioritize some type of traffic over another. - :code:`set traffic-policy priority-queue <policy name> class <class ID> - description <description>` +tc_ is a powerful tool for Traffic Control found at the Linux kernel. +However, its configuration is often considered a cumbersome task. +Fortunately, VyOS eases the job through its CLI, while using ``tc`` as +backend. -* Set a queue length limit in packets, default 1000: - :code:`set traffic-policy priority-queue <policy name> class <class ID> - queue-limit <limit>` +How to make it work +=================== -* Specify a queue type for a traffic class, available queue types: +In order to have VyOS Traffic Control working you need to follow 2 +steps: - * drop-tail - * fair-queue - * random-detect + 1. Create a traffic policy. - :code:`set traffic-policy priority-queue <policy name> class <class ID> - queue-type <type>` + 2. Apply the traffic policy to an interface ingress or egress. + -Default class -############# +But before learning to configure your policy, we will warn you +about the different units you can use and also show you what *classes* +are and how they work, as some policies may require you to configure +them. -* Define a default priority queue: - :code:`set traffic-policy priority-queue <policy name> default` +Units +===== -* Define a maximum queue length for the default traffic class in packets: +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. - :code:`set traffic-policy priority-queue <policy name> default queue-limit - <limit>` +Prefixes +-------- -* Specify the queuing type for the default traffic class, available queue types: +They can be **decimal** prefixes. - * drop-tail - * fair-queue - * random-detect + .. code-block:: none - :code:`set traffic-policy priority-queue <policy name> default queue-type <type>` + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second -Matching rules -************** +Or **binary** prefixes. -* Define a class matching rule: + .. code-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name>` + kibit (2^10 = 1024) kibibit per second + mibit (2^20 = 1024^2) mebibit per second + gibit (2^30 = 1024^3) gibibit per second + tbit (2^40 = 1024^4) tebibit per second -* Add a match rule description: + kibps (1024*8) kibibyte (KiB) per second + mibps (1024^2*8) mebibyte (MiB) per second + gibps (1024^3*8) gibibyte (GiB) per second + tibps (1024^4*8) tebibyte (TiB) per second - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> description <description>` -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): +Suffixes +-------- - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ether destination <MAC address>` +A *bit* is written as **bit**, + + .. code-block:: none -* Specify a match criterion based on a **source MAC address** - (format: xx:xx:xx:xx:xx:xx): + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ether source <MAC address>` +while a *byte* is written as a single **b**. -* Specify a match criterion based on **packet type/protocol**, range 0...65535: + .. code-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ether protocol <number>` + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) -* Specify a match criterion based on **ingress interface**: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> interface <interface>` -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> mark <fwmark>` +.. _classes: -* Specify a match criterion based on **VLAN ID**, range 1...4096: +Classes +======= - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> vif <VLAN ID>` +In the :ref:`creating_a_traffic_policy` section you will see that +some of the policies use *classes*. Those policies let you distribute +traffic into different classes according to different parameters you can +choose. So, a class is just a specific type of traffic you select. -**IPv4** +The ultimate goal of classifying traffic is to give each class a +different treatment. -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ip destination <IPv4 address|port>` +Matching traffic +---------------- -* Specify a match criterion based on **source IPv4 address and/or port**, port - may be specified as number or service name (i.e. ssh): +In order to define which traffic goes into which class, you define +filters (that is, the matching criteria). Packets go through these matching rules +(as in the rules of a firewall) and, if a packet matches the filter, it +is assigned to that class. - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ip source <IPv4 address|port>` +In VyOS, a class is identified by a number you can choose when +configuring it. -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` +.. note:: The meaning of the Class ID is not the same for every type of + policy. Normally policies just need a meaningless number to identify + a class (Class ID), but that does not apply to every policy. + The the number of a class in a Priority Queue it does not only + identify it, it also defines its priority. -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ip protocol <proto>` +.. code-block:: none -**IPv6** + set traffic-policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 destination <IPv6 address|port>` +In the command above, we set the type of policy we are going to +work with and the name we choose for it; a class (so that we can +differentiate some traffic) and an identifiable number for that class; +then we configure a matching rule (or filter) and a name for it. -* Specify a match criterion based on **source IPv6 address and/or port**, port - may be specified as number or service name (i.e. ssh): +A class can have multiple match filters: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 source <IPv6 address|port>` +.. code-block:: none -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 dscp <DSCP value>` +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: +For example: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` +.. code-block:: none -Random Early Detection (RED/WRED) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip source port 80 -RED -*** +This will match TCP traffic with source port 80. -A Random Early Detection (RED) policy starts randomly dropping packets from a -queue before it reaches its queue limit thus avoiding congestion. It is also -beneficial for TCP connections as the gradual dropping of packets acts as a -signal for the sender to decrease its transmission rate, avoiding global TCP -synchronisation. Applicable to outbound traffic only. +There are many parameters you will be able to use in order to match the +traffic you want for a class: -Available commands: + - **Ethernet (protocol, destination address or source address)** + - **Interface name** + - **IPv4 (DSCP value, maximum packet length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **IPv6 (DSCP value, maximum payload length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **Firewall mark** + - **VLAN ID** -* Define a RED policy: +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. - :code:`set traffic-policy random-detect <policy name>` -* Add a description: +.. code-block:: none - :code:`set traffic-policy random-detect <policy name> description <description>` + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + -* Set a bandwidth limit, default auto: +As shown in the example above, one of the possibilities to match packets +is based on marks done by the firewall, `that can give you a great deal of flexibility`_. - :code:`set traffic-policy random-detect <policy name> bandwidth <rate>` +You can also write a description for a filter: - Available suffixes:</u> +.. code-block:: none - * auto (bandwidth limit based on interface speed, default) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" -WRED -**** -In contrast to RED, Weighted Random Early Detection (WRED) differentiates -between classes of traffic in a single queue and assigns different precedence -to traffic flows accordingly; low priority packets are dropped from a queue -earlier than high priority packets. This is achieved by using the first three -bits of the ToS (Type of Service) field to categorise data streams and in -accordance with the defined precedence parameters a decision is made. A WRED -policy is defined with the following parameters: -* precedence -* min-threshold -* max-threshold -* average-packet -* mark-probability -* queue-limit +.. note:: An IPv4 TCP filter will only match packets with an IPv4 header length of + 20 bytes (which is the majority of IPv4 packets anyway). -If the average queue size is lower than the :code:`min-threshold`, an arriving -packet is placed in the queue. If the average queue size is between -:code:`min-threshold` and :code:`max-threshold` an arriving packet is either -dropped or placed in the queue depending on the defined :code:`mark-probability`. -In case the average queue size is larger than :code:`max-threshold`, packets -are dropped. If the current queue size is larger than :code:`queue-limit`, -packets are dropped. The average queue size depends on its former average size -and its current size. If :code:`max-threshold` is set but :code:`min-threshold` -is not, then :code:`min-threshold` is scaled to 50% of :code:`max-threshold`. -In principle, values must be :code:`min-threshold` < :code:`max-threshold` < -:code:`queue-limit`. Applicable to outbound traffic only. -Possible values for WRED parameters: +.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see + https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers -* precedence - IP precedence, first three bits of the ToS field as defined in - RFC791_. - +------------+----------------------+ - | Precedence | Priority | - +============+======================+ - | 7 | Network Control | - +------------+----------------------+ - | 6 | Internetwork Control | - +------------+----------------------+ - | 5 | CRITIC/ECP | - +------------+----------------------+ - | 4 | Flash Override | - +------------+----------------------+ - | 3 | Flash | - +------------+----------------------+ - | 2 | Immediate | - +------------+----------------------+ - | 1 | Priority | - +------------+----------------------+ - | 0 | Routine | - +------------+----------------------+ +Default +------- -* min-threshold - Min value for the average queue length, packets are dropped - if the average queue length reaches this threshold. Range 0...4096, default - is dependent on precedence: +Often you will also have to configure your *default* traffic in the same +way you do with a class. *Default* can be considered a class as it +behaves like that. It contains any traffic that did not match any +of the defined classes, so it is like an open class, a class without +matching filters. - +------------+-----------------------+ - | Precedence | default min-threshold | - +============+=======================+ - | 7 | 16 | - +------------+-----------------------+ - | 6 | 15 | - +------------+-----------------------+ - | 5 | 14 | - +------------+-----------------------+ - | 4 | 13 | - +------------+-----------------------+ - | 3 | 12 | - +------------+-----------------------+ - | 2 | 11 | - +------------+-----------------------+ - | 1 | 10 | - +------------+-----------------------+ - | 0 | 9 | - +------------+-----------------------+ -* max-threshold - Max value for the average queue length, packets are dropped - if this value is exceeded. Range 0...4096 packets, default 18. +Class treatment +--------------- -* average-packet - Average packet size in bytes, default 1024. +Once a class has a filter configured, you will also have to define what +you want to do with the traffic of that class, what specific +Traffic-Control treatment you want to give it. You will have different +possibilities depending on the Traffic Policy you are configuring. -* mark-probability - The fraction of packets (n/probability) dropped from the - queue when the average queue length reaches <code>max-threshold</code>, - default 10. +.. code-block:: none -* queue-limit - Packets are dropped when the current queue length reaches this - value, default 4*<code>max-threshold</code>. + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + +For instance, with :code:`set traffic-policy shaper MY-SHAPER class 30 set-dscp EF` +you would be modifying the DSCP field value of packets in that class to +Expedite Forwarding. + + + DSCP values as per :rfc:`2474` and :rfc:`4595`: -Usage: + +---------+------------+--------+------------------------------+ + | Binary | Configured | Drop | Description | + | value | value | rate | | + +=========+============+========+==============================+ + | 101110 | 46 | - | Expedited forwarding (EF) | + +---------+------------+--------+------------------------------+ + | 000000 | 0 | - | Best effort traffic, default | + +---------+------------+--------+------------------------------+ + | 001010 | 10 | Low | Assured Forwarding(AF) 11 | + +---------+------------+--------+------------------------------+ + | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | + +---------+------------+--------+------------------------------+ + | 001110 | 14 | High | Assured Forwarding(AF) 13 | + +---------+------------+--------+------------------------------+ + | 010010 | 18 | Low | Assured Forwarding(AF) 21 | + +---------+------------+--------+------------------------------+ + | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | + +---------+------------+--------+------------------------------+ + | 010110 | 22 | High | Assured Forwarding(AF) 23 | + +---------+------------+--------+------------------------------+ + | 011010 | 26 | Low | Assured Forwarding(AF) 31 | + +---------+------------+--------+------------------------------+ + | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | + +---------+------------+--------+------------------------------+ + | 011110 | 30 | High | Assured Forwarding(AF) 33 | + +---------+------------+--------+------------------------------+ + | 100010 | 34 | Low | Assured Forwarding(AF) 41 | + +---------+------------+--------+------------------------------+ + | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | + +---------+------------+--------+------------------------------+ + | 100110 | 38 | High | Assured Forwarding(AF) 43 | + +---------+------------+--------+------------------------------+ -:code:`set traffic-policy random-detect <policy-name> precedence -<precedence> [average-packet <bytes> | mark-probability <probability> | -max-threshold <max> | min-threshold <min> | queue-limit <packets>]` -Rate control (TBF) -^^^^^^^^^^^^^^^^^^ -The rate control policy uses the Token Bucket Filter (TBF_) algorithm to limit -the packet flow to a set rate. Short bursts can be allowed to exceed the limit. -Applicable to outbound traffic only. -Available commands: +.. _embed: -* Define a rate control policy: +Embedding one policy into another one +------------------------------------- - :code:`set traffic-policy rate-control <policy-name>` +Often we need to embed one policy into another one. It is possible to do +so on classful policies, by attaching a new policy into a class. For +instance, you might want to apply different policies to the different +classes of a Round-Robin policy you have configured. -* Add a description: +A common example is the case of some policies which, in order to be +effective, they need to be applied to an interface that is directly +connected to the link where the bottleneck is. If your router is not +directly connected to the bottleneck, but some hop before it, you can +emulate the bottleneck by embedding your non-shaping policy into a +classful shaping one so that it takes effect. - :code:`set traffic-policy rate-control <policy-name> description <description>` +You can configure a policy into a class through the ``queue-type`` +setting. -* Specify a bandwidth limit in kbits/s: +.. code-block:: none - :code:`set traffic-policy rate-control <policy-name> bandwidth <rate>` + set traffic-policy shaper FQ-SHAPER bandwidth 1gbit + set traffic-policy shaper FQ-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-SHAPER default queue-type fair-queue - Available suffixes:</u> +As shown in the last command of the example above, the `queue-type` +setting allows these combinations. You will be able to use it +in many policies. - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) -* Specify a burst size in bytes, default 15 kilobytes: - :code:`set traffic-policy rate-control <policy-name> burst <burst-size>` +.. _creating_a_traffic_policy: - Available suffixes: - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) +Creating a traffic policy +========================= -* Specify a latency in milliseconds; the maximum amount of time packets are - allowed to wait in the queue, default 50 milliseconds: +VyOS lets you control traffic in many different ways, here we will cover +every possibility. You can configure as many policies as you want, but +you will only be able to apply one policy per interface and direction +(inbound or outbound). - :code:`set traffic-policy rate-control <policy-name> latency` +Some policies can be combined, you will be able to embed_ a different +policy that will be applied to a class of the main policy. - Available suffixes: +.. hint:: If you are looking for a policy for your outbound traffic but + you do not know what policy you need, you might consider FQ-CoDel_ as + your multipurpose nearly-no-configuration low-delay fair-queue + policy; if delay does not worry you and you want to manually allocate + bandwidth shares to specific traffic, then you should consider + Shaper_. - * secs (seconds) - * ms (milliseconds, default) - * us (microseconds) +Drop Tail +--------- -Round robin (DRR) -^^^^^^^^^^^^^^^^^ +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. -The round robin policy divides available bandwidth between all defined traffic -classes. +This the simplest queue possible you can apply to your traffic. Traffic +must go through a finite queue before it is actually sent. You must +define how many packets that queue can contain. -Available commands: +When a packet is to be sent, it will have to go through that queue, so +the packet will be placed at the tail of it. When the packet completely +goes through it, it will be dequeued emptying its place in the queue and +being eventually handed to the NIC to be actually sent out. -* Define a round robin policy: +Despite the Drop-Tail policy does not slow down packets, if many packets +are to be sent, they could get dropped when trying to get enqueued at +the tail. This can happen if the queue has still not been able to +release enough packets from its head. - :code:`set traffic-policy round-robin <policy-name>` +**Very likely you do not need this simple policy as you cannot get much +from it. Sometimes it is used just to enable logging.** -* Add a description: +.. cfgcmd:: set traffic-policy drop-tail <policy-name> queue-limit <number-of-packets> - :code:`set traffic-policy round-robin <policy-name> description <description>` + Use this command to configure a drop-tail policy (PFIFO). Choose a + unique name for this policy and the size of the queue by setting the + number of packets it can contain (maximum 4294967295). -* Define a traffic class ID, range 2...4095: - :code:`set traffic-policy round-robin <policy-name> class <class>` +Fair Queue +---------- -**Default policy:** +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. -* Define a default priority queue: +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, trying to ensure fairness so +that each flow is able to send data in turn, preventing any single one +from drowning out the rest. - :code:`set traffic-policy round-robin <policy name> default` +.. cfgcmd:: set traffic-policy fair-queue <policy-name> -* Set the number of packets that can be sent per scheduling quantum: + Use this command to create a Fair-Queue policy and give it a name. + It is based on the Stochastic Fairness Queueing and can be applied to + outbound traffic. - :code:`set traffic-policy round-robin <policy name> default quantum <packets>` +The algorithm enqueues packets to hash buckets based on source address, +destination address and source port. Each of these buckets should +represent a unique flow. Because multiple flows may get hashed to the +same bucket, the hashing algorithm is perturbed at configurable +intervals so that the unfairness lasts only for a short while. +Perturbation may however cause some inadvertent packet reordering to +occur. An advisable value could be 10 seconds. -* Define a maximum queue length for the default policy in packets: +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. - :code:`set traffic-policy round-robin <policy name> default queue-limit <limit>` +.. cfgcmd:: set traffic-policy fair-queue <policy-name> hash-interval <seconds>` -* Specify the queuing type for the default policy, available queue types: + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of seconds at which + a new queue algorithm perturbation will occur (maximum 4294967295). - * drop-tail - * fair-queue - * priority (based on the DSCP values in the ToS byte) +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. - :code:`set traffic-policy round-robin <policy name> default queue-type <type>` +.. cfgcmd:: set traffic-policy fair-queue <policy-name> queue-limit <limit> -Matching rules -************** + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of maximum packets + allowed to wait in the queue. Any other packet will be dropped. -* Define a class matching rule: +.. note:: Fair Queue is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and Fair Queue will have no + effect. If there is bandwidth available on the physical link, you can + embed_ Fair-Queue into a classful shaping policy to make sure it owns + the queue. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name>` -* Add a match rule description: - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> description <description>` +.. _FQ-CoDel -* Specify a match criterion based on a **destination MAC address** (format: - xx:xx:xx:xx:xx:xx): +FQ-CoDel +-------- - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ether destination <MAC address>` +| **Queueing discipline** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. -* Specify a match criterion based on a **source MAC address** (format: - xx:xx:xx:xx:xx:xx): +The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and +tries to provide good service between all of them. It also tries to keep +the length of all the queues short. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ether source <MAC address>` +FQ-CoDel fights bufferbloat and reduces latency without the need of +complex configurations. It has become the new default Queueing +Discipline for the interfaces of some GNU/Linux distributions. -* Specify a match criterion based on **packet type/protocol**, range 0...65535: +It uses a stochastic model to classify incoming packets into +different flows and is used to provide a fair share of the bandwidth to +all the flows using the queue. Each flow is managed by the CoDel +queuing discipline. Reordering within a flow is avoided since Codel +internally uses a FIFO queue. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ether protocol <number>` +FQ-CoDel is based on a modified Deficit Round Robin (DRR_) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. -* Specify a match criterion based on **ingress interface**: - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> interface <interface>` +.. note:: FQ-Codel is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and FQ-Codel will have no + effect. If there is bandwidth available on the physical link, you can + embed_ FQ-Codel into a classful shaping policy to make sure it owns + the queue. If you are not sure if you need to embed your FQ-CoDel + policy into a Shaper, do it. -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> mark <fwmark>` +FQ-CoDel is tuned to run ok with its default parameters at 10Gbit +speeds. It might work ok too at other speeds without configuring +anything, but here we will explain some cases when you might want to +tune its parameters. -* Specify a match criterion based on **VLAN ID**, range 1...4096: +When running it at 1Gbit and lower, you may want to reduce the +`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may +want to set it to 600 packets. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> vif <VLAN ID>*` +If you are using FQ-CoDel embedded into Shaper_ and you have large rates +(100Mbit and above), you may consider increasing `quantum` to 8000 or +higher so that the scheduler saves CPU. -**IPv4** +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): +At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps +being ok) you may also want to increase `target` to something like 15ms +and increase `interval` to something around 150 ms. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip destination <IPv4 address|port>` -* Specify a match criterion based on **source IPv4 address and/or port**, port - may be specified as number or service name (i.e. ssh): +.. cfgcmd:: set traffic-policy fq-codel <policy name> codel-quantum <bytes> - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip source <IPv4 address|port>` + Use this command to configure an fq-codel policy, set its name and + the maximum number of bytes (default: 1514) to be dequeued from a + queue at once. -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: +.. cfgcmd:: set traffic-policy fq-codel <policy name> flows <number-of-flows> - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` + Use this command to configure an fq-codel policy, set its name and + the number of sub-queues (default: 1024) into which packets are + classified. -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: +.. cfgcmd:: set traffic-policy fq-codel <policy name> interval <miliseconds> - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip protocol <proto>` + Use this command to configure an fq-codel policy, set its name and + the time period used by the control loop of CoDel to detect when a + persistent queue is developing, ensuring that the measured minimum + delay does not become too stale (default: 100ms). -**IPv6** +.. cfgcmd:: set traffic-policy fq-codel <policy-name> queue-limit <number-of-packets>` -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): + Use this command to configure an fq-codel policy, set its name, and + define a hard limit on the real queue size. When this limit is + reached, new packets are dropped (default: 10240 packets). - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ipv6 destination <IPv6 address|port>` +.. cfgcmd:: set traffic-policy fq-codel <policy-name> target <miliseconds>` -* Specify a match criterion based on **source IPv6 address and/or port**, port - may be specified as number or service name (i.e. ssh): + Use this command to configure an fq-codel policy, set its name, and + define the acceptable minimum standing/persistent queue delay. This + minimum delay is identified by tracking the local minimum queue delay + that packets experience (default: 5ms). - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ipv6 source <IPv6 address|port>` -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: +Example +^^^^^^^ - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ipv6 dscp <DSCP value>` +A simple example of an FQ-CoDel policy working inside a Shaper one. -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` +.. code-block:: none -Traffic shaper -^^^^^^^^^^^^^^ + set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit + set traffic-policy shaper FQ-CODEL-SHAPER 100% + set traffic-policy shaper FQ-CODEL-SHAPER fq-codel -The shaper policy uses the Hierarchical Token Bucket algorithm to allocate -different amounts of bandwidth to different traffic classes. In contrast to -round robin, shaper limits bandwidth allocation by traffic class whereas round -robin divides the total available bandwidth between classes. -Available commands: -* Define a shaper policy: +Limiter +------- - :code:`set traffic-policy shaper <policy-name>` +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. -* Add a description: +Limiter is one of those policies that uses classes_ (Ingress qdisc is +actually classless policy but filters do work in it). - :code:`set traffic-policy shaper <policy-name> description <description>` +The limiter performs basic ingress policing of traffic flows. Multiple +classes of traffic can be defined and traffic limits can be applied to +each class. Although the policer uses a token bucket mechanism +internally, it does not have the capability to delay a packet as a +shaping mechanism does. Traffic exceeding the defined bandwidth limits +is directly dropped. A maximum allowed burst can be configured too. -* Set the available bandwidth for all combined traffic of this policy in kbit/s, - default 100%: +You can configure classes (up to 4090) with different settings and a +default policy which will be applied to any traffic not matching any of +the configured classes. - :code:`set traffic-policy shaper <policy-name> bandwidth <rate>` - Available suffixes: +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. - * % (percentage of total bandwidth) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) -Traffic classes -*************** +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match <match-name> description <description> -* Define a traffic class for a shaper policy, range for class ID is 2...4095: + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), a class matching rule name and its + description. - :code:`set traffic-policy shaper <policy-name> class <class ID>` -* Add a class description: +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. - :code:`set traffic-policy shaper <policy name> class <class ID> description - <description>` -* Specify a bandwidth limit for a class, in kbit/s: +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> bandwidth <rate> - :code:`set traffic-policy shaper <policy-name> class <class ID> bandwidth <rate>` + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the maximum allowed bandwidth for + this class. - Available suffixes: - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> burst <burst-size> -* Set a burst size for a class, the maximum amount of traffic that can be sent, - in bytes: + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the burst size in bytes for this + class (default: 15). - :code:`set traffic-policy shaper <policy-name> class <class ID> - burst <burst-size>` - Available suffixes: +.. cfgcmd:: set traffic-policy limiter <policy-name> default bandwidth <rate> - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. -* Set a bandwidth ceiling for a class in kbit/s: - :code:`set traffic-policy shaper <policy-name> class <class ID> ceiling <rate>` +.. cfgcmd:: set traffic-policy limiter <policy-name> default burst <burst-size> - Available suffixes: + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. - * % (percentage of total bandwidth) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) -* Set the priority of a class for allocation of additional bandwidth, if - unused bandwidth is available. You can set any number from 0 to 7. The - lower the number, the higher the priority. If no value is set for a - classs, it will be internally configured as 0, the highest priority. +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority <value> - :code:`set traffic-policy shaper <policy-name> class <class ID> - priority <priority>` + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), and the priority (0-20, default 20) in + which the rule is evaluated (the lower the number, the higher the + priority). -* Set a queue length limit in packets: + - :code:`set traffic-policy shaper <policy name> class <class ID> queue-limit - <limit>` +Network emulator +---------------- -* Specify a queue type for a traffic class, default fair-queue. Available - queue types: +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. - * drop-tail - * fair-queue - * random-detect - * priority +VyOS Network Emulator policy emulates the conditions you can suffer in a +real network. You will be able to configure things like rate, burst, +delay, packet loss, packet corruption or packet reordering. - :code:`set traffic-policy shaper <policy name> class <class ID> queue-type <type>` +This could be helpful if you want to test how an application behaves +under certain network conditions. -* Modify DSCP field; the DSCP field value of packets in a class can be - rewritten to change the forwarding behaviour and allow for traffic - conditioning: - :code:`set traffic-policy shaper <policy name> class <class ID> set-dscp <value>` +.. cfgcmd:: set traffic-policy network-emulator <policy-name> bandwidth <rate> + + Use this command to configure the maximum rate at which traffic will + be shaped in a Network Emulator policy. Define the name of the policy + and the rate. - DSCP values as per RFC2474_ and RFC4595_: +.. cfgcmd:: set traffic-policy network-emulator <policy-name> burst <burst-size> + + Use this command to configure the burst size of the traffic in a + Network Emulator policy. Define the name of the Network Emulator + policy and its traffic burst size. It will only take effect if you + have configured its bandwidth too. - +---------+------------+--------+------------------------------+ - | Binary | Configured | Drop | Description | - | value | value | rate | | - +=========+============+========+==============================+ - | 101110 | 46 | - | Expedited forwarding (EF) | - +---------+------------+--------+------------------------------+ - | 000000 | 0 | - | Best effort traffic, default | - +---------+------------+--------+------------------------------+ - | 001010 | 10 | Low | Assured Forwarding(AF) 11 | - +---------+------------+--------+------------------------------+ - | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | - +---------+------------+--------+------------------------------+ - | 001110 | 14 | High | Assured Forwarding(AF) 13 | - +---------+------------+--------+------------------------------+ - | 010010 | 18 | Low | Assured Forwarding(AF) 21 | - +---------+------------+--------+------------------------------+ - | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | - +---------+------------+--------+------------------------------+ - | 010110 | 22 | High | Assured Forwarding(AF) 23 | - +---------+------------+--------+------------------------------+ - | 011010 | 26 | Low | Assured Forwarding(AF) 31 | - +---------+------------+--------+------------------------------+ - | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | - +---------+------------+--------+------------------------------+ - | 011110 | 30 | High | Assured Forwarding(AF) 33 | - +---------+------------+--------+------------------------------+ - | 100010 | 34 | Low | Assured Forwarding(AF) 41 | - +---------+------------+--------+------------------------------+ - | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | - +---------+------------+--------+------------------------------+ - | 100110 | 38 | High | Assured Forwarding(AF) 43 | - +---------+------------+--------+------------------------------+ +.. cfgcmd:: set traffic-policy network-emulator <policy-name> network-delay <delay> + + Use this command to configure a Network Emulator policy defining its + name and the fixed amount of time you want to add to all packet going + out of the interface. You can use secs, ms and us. -Matching rules -************** +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-corruption <percent> + + Use this command to emulate noise in a Network Emulator policy. Set + the policy name and the percentage of corrupted packets you want. A + random error will be introduced in a random position for the chosen + percent of packets. -* Define a class matching rule: +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-loss <percent>` + + Use this command to emulate packet-loss conditions in a Network + Emulator policy. Set the policy name and the percentage of loss + packets your traffic will suffer. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name>` +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-reordering <percent>` + + Use this command to emulate packet-reordering conditions in a Network + Emulator policy. Set the policy name and the percentage of reordered + packets your traffic will suffer. -* Add a match rule description: +.. cfgcmd:: set traffic-policy network-emulator <policy-name> queue-limit <limit> + + Use this command to define the length of the queue of your Network + Emulator policy. Set the policy name and the maximum number of + packets (1-4294967295) the queue may hold queued at a time. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> description <description>` -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ether destination <MAC address>` +Priority queue +-------------- -* Specify a match criterion based on a **source MAC address** - (format: xx:xx:xx:xx:xx:xx): +| **Queueing discipline:** PRIO. +| **Applies to:** Outbound traffic. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ether source <MAC address>` -* Specify a match criterion based on **packet type/protocol**, range 0...65535: +The Priority Queue is a classful scheduling policy. It does not delay +packets, it simply dequeues packets according to their priority. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ether protocol <number>` +.. note:: Priority Queue, as other non-shaping policies, is only useful + if your outgoing interface is really full. If it is not, VyOS will + not own the queue and Priority Queue will have no effect. If there is + bandwidth available on the physical link, you can embed_ Priority + Queue into a classful shaping policy to make sure it owns the queue. + In that case packets can be prioritized based on DSCP. -* Specify a match criterion based on **ingress interface**: +Up to seven queues -defined as classes_ with different priorities- can +be configured. Packets are placed into queues based on associated match +criteria. Packets are transmitted from the queues in priority order. If +classes with a higher priority are being filled with packets +continuously, packets from lower priority classes will only be +transmitted after traffic volume from higher priority classes decreases. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> interface <interface>` -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: +.. note:: In Priority Queue we do not define clases with a meaningless + class ID number but with a class priority number (1-7). The lower the + number, the higher the priority. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> mark <fwmark>` -* Specify a match criterion based on **VLAN ID**, range 1...4096: +As with other policies, you can define different type of matching rules +for your classes: - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> vif <VLAN ID>` +.. code-block:: none -**IPv4** + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ip destination <IPv4 address|port>` +As with other policies, you can embed_ other policies into the classes +(and default) of your Priority Queue policy through the ``queue-type`` +setting: -* Specify a match criterion based on **source IPv4 address and/or port**, port - may be specified as number or service name (i.e. ssh): +.. code-block:: none - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ip source <IPv4 address|port>` + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` +.. cfgcmd:: set traffic-policy priority-queue <policy-name> class <class-ID> queue-limit <limit>` -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: + Use this command to configure a Priority Queue policy, set its name, + set a class with a priority from 1 to 7 and define a hard limit on + the real queue size. When this limit is reached, new packets are + dropped. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ip protocol <proto>` -**IPv6** -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): +.. _Random-Detect: - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ipv6 destination <IPv6 address|port>` +Random-Detect +------------- -* Specify a match criterion based on **source IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ipv6 source <IPv6 address|port>` +| **Queueing discipline:** Generalized Random Early Drop. +| **Applies to:** Outbound traffic. -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: +A simple Random Early Detection (RED) policy would start randomly +dropping packets from a queue before it reaches its queue limit thus +avoiding congestion. That is good for TCP connections as the gradual +dropping of packets acts as a signal for the sender to decrease its +transmission rate. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ipv6 dscp <DSCP value>` +In contrast to simple RED, VyOS' Random-Detect uses a Weighted Random +Early Detect policy that prvides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: +This is achieved by using the first three bits of the ToS (Type of +Service) field to categorize data streams and, in accordance with the +defined precedence parameters, a decision is made. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` +IP precedence as defined in :rfc:`791`: -shaper-hfsc (HFSC_ + sfq) -^^^^^^^^^^^^^^^^^^^^^^^^^ + +------------+----------------------+ + | Precedence | Priority | + +============+======================+ + | 7 | Network Control | + +------------+----------------------+ + | 6 | Internetwork Control | + +------------+----------------------+ + | 5 | CRITIC/ECP | + +------------+----------------------+ + | 4 | Flash Override | + +------------+----------------------+ + | 3 | Flash | + +------------+----------------------+ + | 2 | Immediate | + +------------+----------------------+ + | 1 | Priority | + +------------+----------------------+ + | 0 | Routine | + +------------+----------------------+ -TBD -Ingress shaping ---------------- +.. cfgcmd:: set traffic-policy random-detect <policy-name> bandwidth <bandwidth> -The case of ingress shaping. Only a **limiter** policy can be applied directly -for ingress traffic on an interface. It is possible though to use what is -called an Intermediate Functional Block (IFB_) to allow the usage of any policy -on the ingress traffic. + Use this command to configure a Random-Detect policy, set its name + and set the available bandwidth for this policy. -Let's assume eth0 is your WAN link. You created two traffic-policies: `WAN-IN` -and `WAN-OUT`. +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> average-packet <bytes> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what the size of its average-packet should be + (in bytes, default: 1024). -Steps to do: +.. note:: When configuring a Random-Detect policy: **the higher the + precedence number, the higher the priority**. -* First, create the IFB: +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> mark-probability <value> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its mark (drop) probability will be. Set the + probability by giving the N value of the fraction 1/N (default: 10). - :code:`set interfaces input ifb0 description "WAN Input"` -* Apply the `WAN-IN` traffic-policy to ifb0 input. +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> maximum-threshold <packets> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its maximum threshold for random detection will + be (from 0 to 4096 packets, default: 18). At this size, the marking + (drop) probability is maximal. - :code:`set interfaces input ifb0 traffic-policy out WAN-IN` +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> minimum-threshold <packets> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its minimum threshold for random detection will + be (from 0 to 4096 packets). If this value is exceeded, packets + start being eligible for being dropped. -* Redirect traffic from eth0 to ifb0 - :code:`set interfaces ethernet eth0 redirect ifb0` +The default values for the minimum-threshold depend on IP precedence: -Classful policies and traffic matching --------------------------------------- + +------------+-----------------------+ + | Precedence | default min-threshold | + +============+=======================+ + | 7 | 16 | + +------------+-----------------------+ + | 6 | 15 | + +------------+-----------------------+ + | 5 | 14 | + +------------+-----------------------+ + | 4 | 13 | + +------------+-----------------------+ + | 3 | 12 | + +------------+-----------------------+ + | 2 | 11 | + +------------+-----------------------+ + | 1 | 10 | + +------------+-----------------------+ + | 0 | 9 | + +------------+-----------------------+ -`limiter`, `round-robin`, `priority-queue`, `shaper` and `shaper-hfsc` -distribute traffic into different classes with different options. In VyOS, -classes are numbered and work like firewall rules. e.g: -:code:`set traffic-policy shaper SHAPER class 30` +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> queue-limit <packets> + + Use this command to configure a Random-Detect policy and set its + name, then name the IP Precedence for the virtual queue you are + configuring and what the maximum size of its queue will be (from 1 to + 1-4294967295 packets). Packets are dropped when the current queue + length reaches this value. -Matching traffic -^^^^^^^^^^^^^^^^ -A class can have multiple match filters: +If the average queue size is lower than the :code:`min-threshold`, an +arriving packet will be placed in the queue. In the case the average +queue size is between :code:`min-threshold` and :code:`max-threshold`, +then an arriving packet would be either dropped or placed in the queue, +it will depend on the defined :code:`mark-probability`. If the current +queue size is larger than :code:`queue-limit`, then packets will be +dropped. The average queue size depends on its former average size and +its current one. If :code:`max-threshold` is set but +:code:`min-threshold` is not, then :code:`min-threshold` is scaled to +50% of :code:`max-threshold`. In principle, values must be +:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. -.. code-block:: none +One use of this algorithm might be to prevent a backbone overload. - set traffic-policy <POLICY> <POLICY-NAME> class N match MATCH-FILTER-NAME -Example: +Rate control +------------ -.. code-block:: none +| **Queueing discipline:** Tocken Bucket Filter. +| **Applies to:** Outbound traffic. - set traffic-policy shaper SHAPER class 30 match HTTP - set traffic-policy shaper SHAPER class 30 match HTTPs +Rate-Control is a classless policy that limits the packet flow to a set +rate. It is a pure shaper, it does not schedule traffic. Traffic is +filtered based on the expenditure of tokens. Tokens roughly correspond +to bytes. -A match filter contains multiple criteria and will match traffic if all those criteria are true. +Short bursts can be allowed to exceed the limit. On creation, the +Rate-Control traffic is stocked with tokens which correspond to the +amount of traffic that can be burst in one go. Tokens arrive at a steady +rate, until the bucket is full. -For example: +.. cfgcmd:: set traffic-policy rate-control <policy-name> bandwidth <rate> -.. code-block:: none + Use this command to configure a Rate-Control policy, set its name + and the rate limit you want to have. - set traffic-policy shaper SHAPER class 30 match HTTP ip protocol tcp - set traffic-policy shaper SHAPER class 30 match HTTP ip source port 80 +.. cfgcmd:: set traffic-policy rate-control <policy-name> burst <burst-size> -This will match tcp traffic with source port 80. + Use this command to configure a Rate-Control policy, set its name + and the size of the bucket in bytes which will be available for + burst. -description -*********** -.. code-block:: none +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. - set traffic-policy shaper SHAPER class 30 match MATCH description "match filter description" +A very small buffer will soon start dropping packets. -ether -***** +.. cfgcmd:: set traffic-policy rate-control <policy-name> latency -.. code-block:: none + Use this command to configure a Rate-Control policy, set its name + and the maximum amount of time a packet can be queued (default: 50 + ms). - edit traffic-policy shaper SHAPER class 30 match MATCH ether -destination -########### +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. -protocol -######## +.. _DRR: -source -###### +Round robin (DRR) +----------------- -interface -********* +| **Queueing discipline:** Deficit Round Robin. +| **Applies to:** Outbound traffic. -.. code-block:: none +The round-robin policy is a classful scheduler that divides traffic in +different classes_ you can configure (up to 4096). You can embed_ a +new policy into each of those classes (default included). + +Each class is assigned a deficit counter (the number of bytes that a +flow is allowed to transmit when it is its turn) initialized to quantum. +Quantum is a parameter you configure which acts like a credit of fix +bytes the counter receives on each round. Then the Round-Robin policy +starts moving its Round Robin pointer through the queues. If the deficit +counter is greater than the packet's size at the head of the queue, this +packet will be sent and the value of the counter will be decremented by +the packet size. Then, the size of the next packet will be compared to +the counter value again, repeating the process. Once the queue is empty +or the value of the counter is insufficient, the Round-Robin pointer +will move to the next queue. If the queue is empty, the value of the +deficit counter is reset to 0. - edit traffic-policy shaper SHAPER class 30 match MATCH interface <interface-name> +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. -ip -** -.. code-block:: none - edit traffic-policy shaper SHAPER class 30 match MATCH ip +.. cfgcmd:: set traffic-policy round-robin <policy name> class + <class-ID> quantum <packets> -destination -########### + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the quantum for that class. The deficit counter will + add that value each round. -.. code-block:: none +.. cfgcmd:: set traffic-policy round-robin <policy name> class + <class ID> queue-limit <packets> - set destination address IPv4-SUBNET - set destination port U32-PORT + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the queue size in packets. -dscp -#### +As with other policies, Round-Robin can embed_ another policy into a +class through the ``queue-type`` setting. .. code-block:: none - set dscp DSCPVALUE + vyos@vyos# set traffic-policy round-robin DRR class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + -max-length -########## -.. code-block:: none - - set max-length U32-MAXLEN -Will match ipv4 packets with a total length lesser than set value. +.. _Shaper: -protocol -######## +Shaper +------ -.. code-block:: none +| **Queueing discipline:** Hierarchical Token Bucket. +| **Applies to:** Outbound traffic. - set protocol <IP PROTOCOL> -source -###### - -.. code-block:: none +The Shaper policy does not guarantee a low delay, but it does guarantee +bandwidth to different traffic classes and also lets you decide how to +allocate more traffic once the guarantees are met. - set source address IPv4-SUBNET - set source port U32-PORT +Each class can have a guaranteed part of the total bandwidth defined for +the whole policy, so all those shares together should not be higher +than the policy's whole bandwidth. -tcp -### +If guaranteed traffic for a class is met and there is room for more +traffic, the ceiling parameter can be used to set how much more +bandwidth could be used. If guaranteed traffic is met and there are +several classes willing to use their ceilings, the priority parameter +will establish the order in which that additional traffic will be +allocated. Priority can be any number from 0 to 7. The lower the number, +the higher the priority. -.. note:: You must set ip protocol to TCP to use the TCP filters. -.. note:: This filter will only match packets with an IPv4 header length of - 20 bytes (which is the majority of IPv4 packets anyway). +.. cfgcmd:: set traffic-policy shaper <policy-name> bandwidth <rate> -.. code-block:: none + Use this command to configure a Shaper policy, set its name + and the maximum bandwidth for all combined traffic. - set tcp ack -Will match tcp packets with ACK flag set. +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> bandwidth <rate> -.. code-block:: none + Use this command to configure a Shaper policy, set its name, define + a class and set the guaranteed traffic you want to allocate to that + class. - set tcp syn +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> burst <bytes> -Will match tcp packets with SYN flag set. + Use this command to configure a Shaper policy, set its name, define + a class and set the size of the `tocken bucket`_ in bytes, which will + be available to be sent at maximum speed (default: 15Kb). -ipv6 -**** +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> ceiling <bandwidth> -.. code-block:: none + Use this command to configure a Shaper policy, set its name, define + a class and set the maximum speed possible for this class. The + default ceiling value is the bandwidth value. - edit traffic-policy shaper SHAPER class 30 match MATCH ipv6 +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> priority <0-7> -destination -########### + Use this command to configure a Shaper policy, set its name, define + a class and set the priority for usage of available bandwidth once + guarantees have been met. The lower the priority number, the higher + the priority. The default priority value is 0, the highest priority. - .. code-block:: none - set destination address IPv6-SUBNET - set destination port U32-PORT +As with other policies, Shaper can embed_ other policies into its +classes through the ``queue-type`` setting and then configure their +parameters. -dscp -#### .. code-block:: none - set dscp DSCPVALUE + vyos@vyos# set traffic-policy shaper HTB class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) -max-length -########## .. code-block:: none - set max-length U32-MAXLEN + vyos@vyos# set traffic-policy shaper HTB class 10 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + + +Example +^^^^^^^ -Will match ipv6 packets with a payload length lesser than set value. +A simple example of Shaper using priorities. -protocol -######## .. code-block:: none - set protocol IPPROTOCOL + set traffic-policy shaper MY-HTB bandwidth '50mbit' + set traffic-policy shaper MY-HTB class 10 bandwidth '10%' + set traffic-policy shaper MY-HTB class 10 ceiling '15%' + set traffic-policy shaper MY-HTB class 10 match ADDRESS10 ip source address '192.168.10.0/24' + set traffic-policy shaper MY-HTB class 10 priority '0' + set traffic-policy shaper MY-HTB class 10 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB class 20 bandwidth '10%' + set traffic-policy shaper MY-HTB class 20 ceiling '50%' + set traffic-policy shaper MY-HTB class 20 match ADDRESS20 ip source address '192.168.20.0/24' + set traffic-policy shaper MY-HTB class 20 priority '3' + set traffic-policy shaper MY-HTB class 20 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB class 30 bandwidth '10%' + set traffic-policy shaper MY-HTB class 30 ceiling '50%' + set traffic-policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' + set traffic-policy shaper MY-HTB class 30 priority '5' + set traffic-policy shaper MY-HTB class 30 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB default bandwidth '10%' + set traffic-policy shaper MY-HTB default ceiling '100%' + set traffic-policy shaper MY-HTB default priority '7' + set traffic-policy shaper MY-HTB default queue-type 'fair-queue' + + + +.. _ingress-shaping: + +The case of ingress shaping +=========================== + +| **Applies to:** Inbound traffic. + +For the ingress traffic of an interface, there is only one policy you +can directly apply, a **Limiter** policy. This workaround lets you +redirect every incoming traffic to an in-between virtual interface to +which you will be able to apply there an outbound policy. That +in-between virtual interface" is possible because of the configuration +of an Intermediate Functional Block IFB_. That is how it is possible to +do an "ingress shaping". -source -###### .. code-block:: none - set source address IPv6-SUBNET - set source port U32-PORT + set traffic-policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + + set interfaces input ifb0 traffic-policy out MY-INGRESS-SHAPING + set interfaces ethernet eth0 redirect ifb0 -tcp -### -.. note:: You must set ipv6 protocol to TCP to use the TCP filters. -.. note:: This filter will only match IPv6 packets with no header extension, see - http://en.wikipedia.org/wiki/IPv6_packet#Extension_headers for no header - extension. +Applying a traffic policy +========================= -.. code-block:: none - - set tcp ack - -Will match tcp packets with ACK flag set. +Once a traffic-policy is created, you can apply it to an interface: .. code-block:: none - set tcp syn - -Will match tcp packets with SYN flag set. + set interfaces etherhet eth0 traffic-policy out WAN-OUT -mark -**** +You can only apply one policy per interface and direction, but you can +have several policies working at the same time: .. code-block:: none - set traffic-policy shaper SHAPER class 30 match MATCH mark **firewall-mark** + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + set interfaces etherhet eth1 traffic-policy out WAN-OUT + set interfaces ethernet eth2 traffic-policy out LAN-IN + set interfaces ethernet eth2 traffic-policy out LAN-OUT -vif -*** -.. code-block:: none - set traffic-policy shaper SHAPER class 30 match MATCH vif **vlan-tag** -.. code-block:: none - set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' - set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' -.. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) -.. _RFC791: https://tools.ietf.org/html/rfc791 -.. _TBF: https://en.wikipedia.org/wiki/Token_bucket -.. _RFC2474: https://tools.ietf.org/html/rfc2474#page-7 -.. _RFC4595: https://tools.ietf.org/html/rfc4594#page-19 +.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) +.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket .. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve -.. _IFB: http://www.linuxfoundation.org/collaborate/workgroups/networking/ifb +.. _IFB: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb |
