diff options
Diffstat (limited to 'docs/qos.rst')
| -rw-r--r-- | docs/qos.rst | 1114 |
1 files changed, 589 insertions, 525 deletions
diff --git a/docs/qos.rst b/docs/qos.rst index b0997161..eb73456f 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -1,473 +1,603 @@ .. _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. +*********************** +QoS and Traffic Control +*********************** -Creating a traffic policy -^^^^^^^^^^^^^^^^^^^^^^^^^ +The generic name of Quality of Service or Traffic Control involves +things like shaping, scheduling, policing or dropping traffic, 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. -Such configuration takes place under the `traffic-policy` tree. +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. -Available subtrees : -.. code-block:: none +How to make it work +=================== + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + + 1. Create a traffic policy. + + 2. Apply the traffic policy to an interface ingress or egress. + (You can only apply one policy per interface and direction.) + +But before learning to configure your policy, we will quickly 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. + + + +Units +===== + +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. + +Prefixes +-------- + +They can be **decimal** prefixes. + + .. code-block:: none + + 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 + +Or **binary** prefixes. + + .. code-block:: none + + 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 + + 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 + + +Suffixes +-------- + +A *bit* is written as **bit**. + + .. code-block:: none + + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) + +While a *byte* is written as a single **b**. + + .. code-block:: none + + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) - 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 : + +.. _classes: + +Classes +======= + +In the subsection :ref:`creating_a_traffic_policy` 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. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + + +Matching traffic +---------------- + +In order to define which traffic goes to which class, you define filters +(that is, 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. + +In VyOS, a class is identified by a number you can choose when +configuring it. + + +.. note:: When configuring a class, some policies just need a + meaningless number to identify that class (Class ID), but in other + policies, like Priority Queue, the number of the class defines its + priority. + +When you define a class, you will always need to define which traffic +will be assigned to that class. .. code-block:: none - set interfaces ethernet eth0 traffic-policy in WAN-IN - set interfaces etherhet eth0 traffic-policy out WAN-OUT + set traffic-policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> -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. +In the command above, we are setting the type of policy we are going to +work with, the name we choose for it, a class (so that we can +differentiate some traffic) and an identifiable number for that class, +and then we are configuring a matching rule (or filter) and a name for +it. -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. +A class can have multiple match filters: .. 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 '1' - 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 '7' - 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 '1' - 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 '7' - set traffic-policy shaper upload default queue-type 'fair-queue' + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. -Traffic policies in VyOS ------------------------- -An overview of QoS traffic policies supported by VyOS. +For example: -Drop-tail (FIFO) -^^^^^^^^^^^^^^^^ +.. code-block:: none -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. + 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 -Available commands: +This will match TCP traffic with source port 80. -* Define a drop-tail policy (unique name, exclusive to this policy): +There are many parameters you will be able to use in order to match the +traffic you want for a class: - :code:`set traffic-policy drop-tail <policy name>` + - 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 -* Add a description: +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. - :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-block:: none - :code:`set traffic-policy drop-tail <policy name> queue-limit <limit>` + 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 + + -Fair queue (SFQ) -^^^^^^^^^^^^^^^^ +You can also write a description for a filter: -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. +.. code-block:: none -Available commands: + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" -* Define a fair queue policy: - :code:`set traffic-policy fair-queue <policy name>` -* Add a description: +.. 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). - :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: +.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see + https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers - :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>` +Class treatment +--------------- -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. +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, you +will know about them in the :ref:`creating_a_traffic_policy` subsection. -Available commands: +.. code-block:: none -* Define a traffic limiter policy: - :code:`set traffic-policy limiter <policy-name>` -* Add a description: - :code:`set traffic-policy limiter <policy-name> description <description>` + 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) + -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>` +Default +------- -* Add a class description: +Often you will also have to configure what you want to do with traffic +called *default*, in the same way you do with a class. *Default* is just +any traffic which is not matching any of the classes you configured. It +is like a class without filters. - :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>`. +.. _creating_a_traffic_policy: - 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) +Creating a traffic policy +========================= -* Set a burst size for a class, the maximum amount of traffic that can be sent, - in bytes: +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 limiter <policy-name> class <class ID> - burst <burst-size>`. +Some policies let you have different queues inside, so you will be able +to combine policies by assigning a different policy to a subqueue. - Available suffixes: - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) +.. hint:: If you do not know what policy you need for your outbound + traffic, you might want to try FQ-CoDel_ for a multipurpose simple + configuration, you might also be interested in trying Shaper_ if you + don't need to guarantee low delay, or Shaper-HFSC_ when you need to + guarantee a low delay transmission for some specific traffic and you + are not afraid of setting a complex configuration. -Default class -############# +Drop Tail +--------- -* Define a default class for a limiter policy that applies to traffic not - matching any other classes for this policy: +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. - :code:`set traffic-policy limiter <policy name> default` +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. -* Specify a bandwidth limit for the default class, in kbit/s: +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. - :code:`set traffic-policy limiter <policy name> default bandwidth <rate>`. +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. - Available suffixes: +Very likely you do not need this simple policy as you cannot get much +from it. Sometimes it is used just to enable logging. - * 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 drop-tail <policy-name> queue-limit <number-of-packets> -* Set a burst size for the default class, the maximum amount of traffic that - can be sent, in bytes: + 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). - :code:`set traffic-policy limiter <policy-name> default burst <burst-size>`. - Available suffixes: +Fair Queue +---------- - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. -* 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): +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 limiter <policy name> default priority <priority>` +.. cfgcmd:: set traffic-policy fair-queue <policy-name> -Matching rules -************** + Use this command to create a Fair-Queue policy, which is based on the + Stochastic Fairness Queueing and can be applied to outbound traffic. -* Define a traffic class matching rule: +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. - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name>` +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. -* Add a description: +.. cfgcmd:: set traffic-policy fair-queue <policy-name> hash-interval <seconds>` - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> description <description>` + 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). -* 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): +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 limiter <policy name> class <class ID> - priority <priority>` +.. cfgcmd:: set traffic-policy fair-queue <policy-name> queue-limit <limit> -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): + 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. - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ether destination <MAC address>` +.. 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. -* 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: +.. _FQ-QoDel - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ether protocol <number>` +FQ-CoDel +-------- -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: +| **Queueing discipline** Fair/Flow Queue CoDel +| **Applies to:** Outbound Traffic - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> mark <fwmark>` +The FQ-CoDel policy 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 **VLAN ID**, range 1...4096: +FQ-Codel 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 such 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 limiter <policy name> class <class ID> match - <match name> vif <VLAN ID>` +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. -**IPv4** +VyOS let you customize FQ-CoDel parameters, but very likely it will work +ok with its default values. -* 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>` +.. 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. -* 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: +Limiter +------- - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: +Limiter is one of those policies that uses classes_. (Ingress qdisc is +actually classless but filters do work with it.) - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ip protocol <proto>` +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. -**IPv6** +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. -* 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>` +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. -* 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>` +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match <match-name> description <description> -* Specify a match criterion based on **DSCP (Differentiated Services Code - Point) value**, DSCP value may be specified as decimal or hexadecimal number: + 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 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: +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. - :code:`set traffic-policy limiter <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` -Network emulator -^^^^^^^^^^^^^^^^ +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> bandwidth <rate> -The network emulator policy emulates WAN traffic, which is useful for testing -purposes. Applicable to outbound traffic only. + 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 commands: -* Define a network emulator policy: +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> burst <burst-size> - :code:`set traffic-policy network-emulator <policy name>` + 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). -* Add a description: - :code:`set traffic-policy network-emulator <policy name> description <description>` +.. cfgcmd:: set traffic-policy limiter <policy-name> default bandwidth <rate> -* Specify a bandwidth limit in kbit/s: + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. - :code:`set traffic-policy network-emulator <policy name> bandwidth <rate>` - Available suffixes: +.. cfgcmd:: set traffic-policy limiter <policy-name> default burst <burst-size> - * 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) + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. -* 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>` +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority <value> - Available suffixes: + 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). - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) + -* Define a delay between packets: +Network emulator +---------------- - :code:`set traffic-policy network-emulator <policy name> network-delay <delay>` +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter) +| **Applies to:** Outbound traffic. - Available suffixes: +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. - * secs (seconds) - * ms (milliseconds, default) - * us (microseconds) +This could be helpful if you want to test how an application behaves +under certain network conditions. -* Set a percentage of corrupted of packets (one bit flip, unchanged checksum): - :code:`set traffic-policy network-emulator <policy name> packet-corruption - <percent>` +.. 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. + +.. 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. -* Set a percentage of random packet loss: +.. 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. Default: ms. - :code:`set traffic-policy network-emulator <policy name> packet-loss <percent>` +.. 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. -* Set a percentage of packets for random reordering: +.. 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 network-emulator <policy name> packet-reordering +.. 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. + +.. 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. -* 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. +| **Queueing discipline:** PRIO +| **Applies to:** Outbound traffic -Available commands: -* Define a priority queue: +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 priority-queue <policy name>` +.. 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. -* Add a description: +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 priority-queue <policy name> description <description>` -Traffic classes -*************** +.. note:: In Priority Queue we do not define clases with a class ID + number but with a class priority number (1-7). The lower the number, + the higher the priority. -* 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>` +As with other policies, you can define different type of matching rules +for your classes: -* Add a class description: +.. code-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> - description <description>` + 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 -* Set a queue length limit in packets, default 1000: - :code:`set traffic-policy priority-queue <policy name> class <class ID> - queue-limit <limit>` +.. cfgcmd:: set traffic-policy priority-queue <policy name> class + <class-priority-number> codel-quantum <bytes> + + Use this command to configure a Priority Queue, set its name, set a + class with a priority from 1 to 7 and set the maximum number of bytes + (default: 1514) to be dequeued from a queue at once when using an + fq-codel queue. + + +.. cfgcmd:: set traffic-policy priority-queue <policy name> class + <class-priority-number> flows <number-of-flows> + + Use this command to configure a Priority Queue, set its name, set a + class with a priority from 1 to 7 and set the number of sub-queues + (default: 1024) into which packets are classified when using an + fq-codel queue. + +.. cfgcmd:: set traffic-policy priority-queue <policy name> class + <class-priority-number> interval <miliseconds> + + Use this command to configure a Priority Queue, set its name, set a + class with a priority from 1 to 7 and set the time period used by the + control loop of CoDel to detect when a persistent queue is + developing. It can be used when an fq-codel queue is configured. + +.. cfgcmd:: set traffic-policy priority-queue <policy-name> class + <class-ID> queue-limit <limit>` + + Use this command to configure a Priority Queue, set its name, set a + class with a priority from 1 to 7 and set the xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx * Specify a queue type for a traffic class, available queue types: @@ -479,7 +609,7 @@ Traffic classes queue-type <type>` Default class -############# +""""""""""""" * Define a default priority queue: @@ -499,7 +629,7 @@ Default class :code:`set traffic-policy priority-queue <policy name> default queue-type <type>` Matching rules -************** +"""""""""""""" * Define a class matching rule: @@ -595,11 +725,15 @@ Matching rules :code:`set traffic-policy priority-queue <policy name> class <class ID> match <match name> ipv6 protocol <proto>` + Random Early Detection (RED/WRED) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------- RED -*** +^^^ + +| **Queueing discipline:** +| **Applies to:** 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 @@ -631,8 +765,12 @@ Available commands: * mbps (megabytes per second) * gbps (gigabytes per second) + WRED -**** +^^^^ + +| **Queueing discipline:** +| **Applies to:** In contrast to RED, Weighted Random Early Detection (WRED) differentiates between classes of traffic in a single queue and assigns different precedence @@ -729,7 +867,10 @@ Usage: max-threshold <max> | min-threshold <min> | queue-limit <packets>]` Rate control (TBF) -^^^^^^^^^^^^^^^^^^ +------------------ + +| **Queueing discipline:** +| **Applies to:** 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. @@ -780,7 +921,10 @@ Available commands: * us (microseconds) Round robin (DRR) -^^^^^^^^^^^^^^^^^ +----------------- + +| **Queueing discipline:** +| **Applies to:** The round robin policy divides available bandwidth between all defined traffic classes. @@ -822,7 +966,7 @@ Available commands: :code:`set traffic-policy round-robin <policy name> default queue-type <type>` Matching rules -************** +"""""""""""""" * Define a class matching rule: @@ -918,13 +1062,26 @@ Matching rules :code:`set traffic-policy round-robin <policy name> class <class ID> match <match name> ipv6 protocol <proto>` + +.. _Shaper: + Traffic shaper -^^^^^^^^^^^^^^ +-------------- + +| **Queueing discipline:** +| **Applies to:** -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. + + +DEFAULT PRIORITY: 0 +DEFAULT CEILING: SAME AS BANDWIDTH (so no borrowing) + + + +VyOS shaper uses the Hierarchical Token Bucket algorithm to optimally +allocate different amounts of bandwidth to different traffic classes +while being able to define guaranteed bandwidth and shared bandwidth for +different conditions. Available commands: @@ -952,7 +1109,7 @@ Available commands: * gbps (gigabytes per second) Traffic classes -*************** +""""""""""""""" * Define a traffic class for a shaper policy, range for class ID is 2...4095: @@ -1064,7 +1221,7 @@ Traffic classes +---------+------------+--------+------------------------------+ Matching rules -************** +"""""""""""""" * Define a class matching rule: @@ -1160,252 +1317,159 @@ Matching rules :code:`set traffic-policy shaper <policy name> class <class ID> match <match name> ipv6 protocol <proto>` -shaper-hfsc (HFSC_ + sfq) -^^^^^^^^^^^^^^^^^^^^^^^^^ - -TBD - -Ingress shaping ---------------- - -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. - -Let's assume eth0 is your WAN link. You created two traffic-policies: `WAN-IN` -and `WAN-OUT`. - -Steps to do: - -* First, create the IFB: - - :code:`set interfaces input ifb0 description "WAN Input"` - -* Apply the `WAN-IN` traffic-policy to ifb0 input. - - :code:`set interfaces input ifb0 traffic-policy out WAN-IN` - -* Redirect traffic from eth0 to ifb0 - - :code:`set interfaces ethernet eth0 redirect ifb0` - -Classful policies and traffic matching --------------------------------------- - -`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` - -Matching traffic -^^^^^^^^^^^^^^^^ - -A class can have multiple match filters: - -.. code-block:: none - - set traffic-policy <POLICY> <POLICY-NAME> class N match MATCH-FILTER-NAME - -Example: - -.. code-block:: none - - set traffic-policy shaper SHAPER class 30 match HTTP - set traffic-policy shaper SHAPER class 30 match HTTPs - -A match filter contains multiple criteria and will match traffic if all those criteria are true. - -For example: - -.. code-block:: none - - 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 - -This will match tcp traffic with source port 80. - -description -*********** - -.. code-block:: none - - set traffic-policy shaper SHAPER class 30 match MATCH description "match filter description" - -ether -***** - -.. code-block:: none - - edit traffic-policy shaper SHAPER class 30 match MATCH ether - -destination -########### - -protocol -######## - -source -###### - -interface -********* -.. code-block:: none - - edit traffic-policy shaper SHAPER class 30 match MATCH interface <interface-name> - -ip -** -.. code-block:: none - - edit traffic-policy shaper SHAPER class 30 match MATCH ip - -destination -########### +.. _Shaper-HFSC -.. code-block:: none - - set destination address IPv4-SUBNET - set destination port U32-PORT - -dscp -#### +shaper-hfsc (HFSC_ + sfq) +------------------------- -.. code-block:: none +| **Queueing discipline:** +| **Applies to:** - set dscp DSCPVALUE +TBD -max-length -########## -.. code-block:: none - set max-length U32-MAXLEN +.. _embed -Will match ipv4 packets with a total length lesser than set value. +Embedding a policy into a another one +===================================== -protocol -######## +You can embed a non-shaping policy into a classful shaping policy, as in +the example below: .. code-block:: none - set protocol <IP PROTOCOL> + set traffic-policy shaper SHAPER_FOR_FAIR-QUEUE bandwidth '50mbit' + set traffic-policy shaper SHAPER_FOR_FAIR-QUEUE default bandwidth '50mbit' + set traffic-policy shaper SHAPER_FOR_FAIR-QUEUE default queue-type 'fair-queue' -source -###### -.. code-block:: none - set source address IPv4-SUBNET - set source port U32-PORT -tcp -### -.. note:: You must set ip protocol to TCP to use the TCP filters. +Applying a traffic policy +========================= -.. note:: This filter will only match packets with an IPv4 header length of - 20 bytes (which is the majority of IPv4 packets anyway). +Once a traffic-policy is created, you can apply it to an interface: .. code-block:: none - set tcp ack - -Will match tcp packets with ACK flag set. - -.. code-block:: none + set interfaces etherhet eth0 traffic-policy out WAN-OUT - set tcp syn -Will match tcp packets with SYN flag set. -ipv6 -**** +You can have serveral policies running at the same time: .. code-block:: none - edit traffic-policy shaper SHAPER class 30 match MATCH ipv6 + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + set interfaces ethernet eth1 traffic-policy out LAN-OUT -destination -########### - .. code-block:: none - set destination address IPv6-SUBNET - set destination port U32-PORT -dscp -#### +.. _ingress-shaping: -.. code-block:: none +The case of ingress shaping +=========================== - set dscp DSCPVALUE +| **Queueing discipline:** +| **Applies to:** -max-length -########## +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. -.. code-block:: none +Let's assume eth0 is your WAN link. You created two traffic-policies: `WAN-IN` +and `WAN-OUT`. - set max-length U32-MAXLEN +Steps to do: -Will match ipv6 packets with a payload length lesser than set value. +* First, create the IFB: -protocol -######## + :code:`set interfaces input ifb0 description "WAN Input"` -.. code-block:: none +* Apply the `WAN-IN` traffic-policy to ifb0 input. - set protocol IPPROTOCOL + :code:`set interfaces input ifb0 traffic-policy out WAN-IN` -source -###### +* Redirect traffic from eth0 to ifb0 -.. code-block:: none + :code:`set interfaces ethernet eth0 redirect ifb0` - set source address IPv6-SUBNET - set source port U32-PORT -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 - https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers for no header - extension. -.. code-block:: none +A Real-World Example +==================== - set tcp ack +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. -Will match tcp packets with ACK flag set. +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 tcp syn - -Will match tcp packets with SYN flag set. - -mark -**** - -.. 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' - set traffic-policy shaper SHAPER class 30 match MATCH mark **firewall-mark** -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: https://en.wikipedia.org/wiki/Tc_(Linux) .. _TBF: https://en.wikipedia.org/wiki/Token_bucket |