diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_static/images/virt-libvirt-01.png | bin | 0 -> 33227 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-02.png | bin | 0 -> 30981 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-03.png | bin | 0 -> 24547 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-04.png | bin | 0 -> 28896 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-05.png | bin | 0 -> 38080 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-06.png | bin | 0 -> 28784 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-qc-01.png | bin | 0 -> 33468 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-qc-02.png | bin | 0 -> 26749 bytes | |||
| -rw-r--r-- | docs/_static/images/virt-libvirt-qc-03.png | bin | 0 -> 28278 bytes | |||
| -rw-r--r-- | docs/appendix/vyos-on-virtual-environments.rst | 168 | ||||
| -rw-r--r-- | docs/contributing/build-vyos.rst | 6 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/qos.rst | 1890 | ||||
| -rw-r--r-- | docs/services/console-server.rst | 188 | ||||
| -rw-r--r-- | docs/services/index.rst | 1 |
15 files changed, 1174 insertions, 1080 deletions
diff --git a/docs/_static/images/virt-libvirt-01.png b/docs/_static/images/virt-libvirt-01.png Binary files differnew file mode 100644 index 00000000..06baea8e --- /dev/null +++ b/docs/_static/images/virt-libvirt-01.png diff --git a/docs/_static/images/virt-libvirt-02.png b/docs/_static/images/virt-libvirt-02.png Binary files differnew file mode 100644 index 00000000..b6c4b379 --- /dev/null +++ b/docs/_static/images/virt-libvirt-02.png diff --git a/docs/_static/images/virt-libvirt-03.png b/docs/_static/images/virt-libvirt-03.png Binary files differnew file mode 100644 index 00000000..ac3891f0 --- /dev/null +++ b/docs/_static/images/virt-libvirt-03.png diff --git a/docs/_static/images/virt-libvirt-04.png b/docs/_static/images/virt-libvirt-04.png Binary files differnew file mode 100644 index 00000000..b1218597 --- /dev/null +++ b/docs/_static/images/virt-libvirt-04.png diff --git a/docs/_static/images/virt-libvirt-05.png b/docs/_static/images/virt-libvirt-05.png Binary files differnew file mode 100644 index 00000000..5579c281 --- /dev/null +++ b/docs/_static/images/virt-libvirt-05.png diff --git a/docs/_static/images/virt-libvirt-06.png b/docs/_static/images/virt-libvirt-06.png Binary files differnew file mode 100644 index 00000000..e0983d23 --- /dev/null +++ b/docs/_static/images/virt-libvirt-06.png diff --git a/docs/_static/images/virt-libvirt-qc-01.png b/docs/_static/images/virt-libvirt-qc-01.png Binary files differnew file mode 100644 index 00000000..49867bd0 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-01.png diff --git a/docs/_static/images/virt-libvirt-qc-02.png b/docs/_static/images/virt-libvirt-qc-02.png Binary files differnew file mode 100644 index 00000000..a71b8f64 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-02.png diff --git a/docs/_static/images/virt-libvirt-qc-03.png b/docs/_static/images/virt-libvirt-qc-03.png Binary files differnew file mode 100644 index 00000000..4eefaa58 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-03.png diff --git a/docs/appendix/vyos-on-virtual-environments.rst b/docs/appendix/vyos-on-virtual-environments.rst new file mode 100644 index 00000000..59edcfda --- /dev/null +++ b/docs/appendix/vyos-on-virtual-environments.rst @@ -0,0 +1,168 @@ +.. _vyos-on-virtual-environments: + +Running in Virtual Environments +###################### + +Libvirt Qemu/KVM +***************** + +Libvirt is an open-source API, daemon and management tool for managing platform virtualization. +There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. +In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. + +CLI +=== + +Deploy from ISO +--------------- + +Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. +The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. + +.. code-block:: none + + $ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r1`` + +.. code-block:: none + + $ virsh console vyos_r1 + + Connected to domain vyos_r1 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ install image + +After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. + +Deploy from qcow2 +----------------- +The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + +Create VM with ``import`` qcow2 disk option. + +.. code-block:: none + + $ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r2`` + +.. code-block:: none + + $ virsh console vyos_r2 + + Connected to domain vyos_r2 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ + +The system is fully operational. + +Virt-manager +============ +The virt-manager application is a desktop user interface for managing virtual machines through libvirt. +On the linux open :abbr:`VMM (Virtual Machine Manager)`. + +Deploy from ISO +--------------- + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Local install media`` (ISO) + +.. figure:: /_static/images/virt-libvirt-01.png + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.png + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +7. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.png + +Deploy from qcow2 +----------------- + +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Import existing disk`` image + +.. figure:: /_static/images/virt-libvirt-qc-01.png + +3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-qc-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +6. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.png + + +Proxmox +***************** + +References +---------- +https://www.proxmox.com/en/proxmox-ve + diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 51400eaf..d72f4b07 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -231,7 +231,7 @@ container, it includes all dependencies for compiling supported packages. $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ - vyos-builder scripts/build-packages + vyos-build scripts/build-packages .. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is required to build the `vyos-strongswan` package @@ -251,7 +251,7 @@ Executed from the root of `vyos-build` $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ - vyos-builder scripts/build-packages -b <package> + vyos-build scripts/build-packages -b <package> .. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is only needed when building `vyos-strongswan` and can be ignored on other packages. @@ -280,7 +280,7 @@ Example using `git@github.com:myname/vyos-1x.git` repository to build vyos-1x: $ cd .. $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ - vyos-builder scripts/build-packages -b vyos-1x + vyos-build scripts/build-packages -b vyos-1x .. note:: You need to git pull manually after you commit to the remote and before rebuilding, the local repository won't be updated automatically. diff --git a/docs/index.rst b/docs/index.rst index edb50f77..8b5c4e5d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,6 +59,7 @@ VyOS User Guide appendix/vyos-on-vmware appendix/vyos-on-baremetal appendix/vyos-on-clouds + appendix/vyos-on-virtual-environments appendix/migrate-from-vyatta appendix/command-scripting appendix/http-api diff --git a/docs/qos.rst b/docs/qos.rst index 2e136b17..51ed0893 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -1,1413 +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>` +*** +QoS +*** -Traffic classes -*************** +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. -* Define a traffic class, each class is a separate queue, range for class ID - is 1...7, while 1 being the lowest priority: +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. - :code:`set traffic-policy priority-queue <policy name> class <class ID>` -* Add a class description: +How to make it work +=================== - :code:`set traffic-policy priority-queue <policy name> class <class ID> - description <description>` +In order to have VyOS Traffic Control working you need to follow 2 +steps: -* Set a queue length limit in packets, default 1000: + 1. Create a traffic policy. - :code:`set traffic-policy priority-queue <policy name> class <class ID> - queue-limit <limit>` + 2. Apply the traffic policy to an interface ingress or egress. + -* Specify a queue type for a traffic class, available queue types: +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. - * drop-tail - * fair-queue - * random-detect - :code:`set traffic-policy priority-queue <policy name> class <class ID> - queue-type <type>` +Units +===== -Default class -############# +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. -* Define a default priority queue: +Prefixes +-------- - :code:`set traffic-policy priority-queue <policy name> default` +They can be **decimal** prefixes. -* Define a maximum queue length for the default traffic class in packets: + .. code-block:: none - :code:`set traffic-policy priority-queue <policy name> default queue-limit - <limit>` + 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 -* Specify the queuing type for the default traffic class, available queue types: +Or **binary** prefixes. - * drop-tail - * fair-queue - * random-detect + .. code-block:: none - :code:`set traffic-policy priority-queue <policy name> default queue-type <type>` + 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 -Matching rules -************** + 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 -* Define a class matching rule: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name>` +Suffixes +-------- -* Add a match rule description: +A *bit* is written as **bit**, + + .. code-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> description <description>` + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): +while a *byte* is written as a single **b**. - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ether destination <MAC address>` + .. code-block:: none -* Specify a match criterion based on a **source MAC address** - (format: xx:xx:xx:xx:xx:xx): + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) - :code:`set traffic-policy priority-queue <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 priority-queue <policy name> class <class ID> match - <match name> ether protocol <number>` -* Specify a match criterion based on **ingress interface**: +.. _classes: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> interface <interface>` +Classes +======= -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: +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. - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> mark <fwmark>` +The ultimate goal of classifying traffic is to give each class a +different treatment. -* Specify a match criterion based on **VLAN ID**, range 1...4096: - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> vif <VLAN ID>` +Matching traffic +---------------- -**IPv4** +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. -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): +In VyOS, a class is identified by a number you can choose when +configuring it. - :code:`set traffic-policy priority-queue <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): +.. 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. - :code:`set traffic-policy priority-queue <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-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` + set traffic-policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> -* 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>` +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. -**IPv6** +A class can have multiple match filters: -* 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-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 destination <IPv6 address|port>` + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs -* 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 match filter can contain multiple criteria and will match traffic if +all those criteria are true. - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 source <IPv6 address|port>` +For example: -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: +.. code-block:: none - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 dscp <DSCP value>` + 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 -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: +This will match TCP traffic with source port 80. - :code:`set traffic-policy priority-queue <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` +There are many parameters you will be able to use in order to match the +traffic you want for a class: -Random Early Detection (RED/WRED) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - **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** -RED -*** +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. -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. -Available commands: +.. code-block:: none -* Define a RED policy: + 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 + + - :code:`set traffic-policy random-detect <policy name>` +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`_. -* Add a description: +You can also write a description for a filter: - :code:`set traffic-policy random-detect <policy name> description <description>` +.. code-block:: none -* Set a bandwidth limit, default auto: + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" - :code:`set traffic-policy random-detect <policy name> bandwidth <rate>` - Available suffixes:</u> - * 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) +.. 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). -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: +.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see + https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers -* precedence -* min-threshold -* max-threshold -* average-packet -* mark-probability -* queue-limit -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. +Default +------- -Possible values for WRED parameters: +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 - IP precedence, first three bits of the ToS field as defined in - :rfc:`791`. - +------------+----------------------+ - | Precedence | Priority | - +============+======================+ - | 7 | Network Control | - +------------+----------------------+ - | 6 | Internetwork Control | - +------------+----------------------+ - | 5 | CRITIC/ECP | - +------------+----------------------+ - | 4 | Flash Override | - +------------+----------------------+ - | 3 | Flash | - +------------+----------------------+ - | 2 | Immediate | - +------------+----------------------+ - | 1 | Priority | - +------------+----------------------+ - | 0 | Routine | - +------------+----------------------+ +Class treatment +--------------- -* 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: +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. - +------------+-----------------------+ - | Precedence | default min-threshold | - +============+=======================+ - | 7 | 16 | - +------------+-----------------------+ - | 6 | 15 | - +------------+-----------------------+ - | 5 | 14 | - +------------+-----------------------+ - | 4 | 13 | - +------------+-----------------------+ - | 3 | 12 | - +------------+-----------------------+ - | 2 | 11 | - +------------+-----------------------+ - | 1 | 10 | - +------------+-----------------------+ - | 0 | 9 | - +------------+-----------------------+ +.. code-block:: none -* max-threshold - Max value for the average queue length, packets are dropped - if this value is exceeded. Range 0...4096 packets, default 18. + 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. -* average-packet - Average packet size in bytes, default 1024. -* mark-probability - The fraction of packets (n/probability) dropped from the - queue when the average queue length reaches <code>max-threshold</code>, - default 10. + DSCP values as per :rfc:`2474` and :rfc:`4595`: -* queue-limit - Packets are dropped when the current queue length reaches this - value, default 4*<code>max-threshold</code>. + +---------+------------+--------+------------------------------+ + | 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 | + +---------+------------+--------+------------------------------+ -Usage: -: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. +.. _embed: -Available commands: +Embedding one policy into another one +------------------------------------- -* Define a rate control policy: +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. - :code:`set traffic-policy rate-control <policy-name>` +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. -* Add a description: +You can configure a policy into a class through the ``queue-type`` +setting. - :code:`set traffic-policy rate-control <policy-name> description <description>` +.. code-block:: none -* Specify a bandwidth limit in kbits/s: + 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 - :code:`set traffic-policy rate-control <policy-name> bandwidth <rate>` +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. - Available suffixes:</u> - * 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: +.. _creating_a_traffic_policy: - :code:`set traffic-policy rate-control <policy-name> burst <burst-size>` - Available suffixes: +Creating a traffic policy +========================= - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) +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). -* Specify a latency in milliseconds; the maximum amount of time packets are - allowed to wait in the queue, default 50 milliseconds: +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. - :code:`set traffic-policy rate-control <policy-name> latency` +.. 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_. - Available suffixes: +Drop Tail +--------- - * secs (seconds) - * ms (milliseconds, default) - * us (microseconds) +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. -Round robin (DRR) -^^^^^^^^^^^^^^^^^ +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. -The round robin policy divides available bandwidth between all defined traffic -classes. +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. -Available commands: +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. -* Define a round robin policy: +**Very likely you do not need this simple policy as you cannot get much +from it. Sometimes it is used just to enable logging.** - :code:`set traffic-policy round-robin <policy-name>` +.. cfgcmd:: set traffic-policy drop-tail <policy-name> queue-limit <number-of-packets> -* Add a 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). - :code:`set traffic-policy round-robin <policy-name> description <description>` -* Define a traffic class ID, range 2...4095: +Fair Queue +---------- - :code:`set traffic-policy round-robin <policy-name> class <class>` +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. -**Default policy:** +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. -* Define a default priority queue: +.. cfgcmd:: set traffic-policy fair-queue <policy-name> - :code:`set traffic-policy round-robin <policy name> default` + 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. -* Set the number of packets that can be sent per scheduling quantum: +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 round-robin <policy name> default quantum <packets>` +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. -* Define a maximum queue length for the default policy in packets: +.. cfgcmd:: set traffic-policy fair-queue <policy-name> hash-interval <seconds>` - :code:`set traffic-policy round-robin <policy name> default queue-limit <limit>` + 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 queuing type for the default policy, available queue types: +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. - * drop-tail - * fair-queue - * priority (based on the DSCP values in the ToS byte) +.. cfgcmd:: set traffic-policy fair-queue <policy-name> queue-limit <limit> - :code:`set traffic-policy round-robin <policy name> default queue-type <type>` + 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. -Matching rules -************** +.. 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. -* Define a class matching rule: - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name>` -* Add a match rule description: +.. _FQ-CoDel - :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): +| **Queueing discipline** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ether destination <MAC address>` +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. -* Specify a match criterion based on a **source MAC address** (format: - xx:xx:xx:xx:xx:xx): +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. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ether source <MAC address>` +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. -* Specify a match criterion based on **packet type/protocol**, range 0...65535: +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. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ether protocol <number>` -* Specify a match criterion based on **ingress 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. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> interface <interface>` -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: +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. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> mark <fwmark>` +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. -* Specify a match criterion based on **VLAN ID**, range 1...4096: +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. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> vif <VLAN ID>*` +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. -**IPv4** +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. -* 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 round-robin <policy name> class <class ID> match - <match name> ip destination <IPv4 address|port>` +.. cfgcmd:: set traffic-policy fq-codel <policy name> codel-quantum <bytes> -* Specify a match criterion based on **source IPv4 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 + the maximum number of bytes (default: 1514) to be dequeued from a + queue at once. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip source <IPv4 address|port>` +.. cfgcmd:: set traffic-policy fq-codel <policy name> flows <number-of-flows> -* 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 fq-codel policy, set its name and + the number of sub-queues (default: 1024) into which packets are + classified. - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip dscp <DSCP value>` +.. cfgcmd:: set traffic-policy fq-codel <policy name> interval <miliseconds> -* 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 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). - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ip protocol <proto>` +.. cfgcmd:: set traffic-policy fq-codel <policy-name> queue-limit <number-of-packets>` -**IPv6** + 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). -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): +.. cfgcmd:: set traffic-policy fq-codel <policy-name> target <miliseconds>` - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ipv6 destination <IPv6 address|port>` + 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). -* 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 round-robin <policy name> class <class ID> match - <match name> ipv6 source <IPv6 address|port>` +Example +^^^^^^^ -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: +A simple example of an FQ-CoDel policy working inside a Shaper one. - :code:`set traffic-policy round-robin <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-block:: none - :code:`set traffic-policy round-robin <policy name> class <class ID> match - <match name> ipv6 protocol <proto>` + 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 -Traffic shaper -^^^^^^^^^^^^^^ -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: +Limiter +------- -* Define a shaper policy: +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. - :code:`set traffic-policy shaper <policy-name>` +Limiter is one of those policies that uses classes_ (Ingress qdisc is +actually classless policy but filters do work in it). -* Add a 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. - :code:`set traffic-policy shaper <policy-name> description <description>` +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. -* Set the available bandwidth for all combined traffic of this policy in kbit/s, - default 100%: - :code:`set traffic-policy shaper <policy-name> bandwidth <rate>` +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. - Available suffixes: - * % (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) +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match <match-name> description <description> -Traffic classes -*************** + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), a class matching rule name and its + description. -* Define a traffic class for a shaper policy, range for class ID is 2...4095: - :code:`set traffic-policy shaper <policy-name> class <class ID>` +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. -* Add a class description: - :code:`set traffic-policy shaper <policy name> class <class ID> description - <description>` +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> bandwidth <rate> -* Specify a bandwidth limit for a class, in kbit/s: + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the maximum allowed bandwidth for + this class. - :code:`set traffic-policy shaper <policy-name> class <class ID> bandwidth <rate>` - Available suffixes: +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> 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, + a class identifier (1-4090) and the burst size in bytes for this + class (default: 15). -* Set a burst size for a class, the maximum amount of traffic that can be sent, - in bytes: - :code:`set traffic-policy shaper <policy-name> class <class ID> - burst <burst-size>` +.. cfgcmd:: set traffic-policy limiter <policy-name> default bandwidth <rate> - Available suffixes: + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) -* Set a bandwidth ceiling for a class in kbit/s: +.. cfgcmd:: set traffic-policy limiter <policy-name> default burst <burst-size> - :code:`set traffic-policy shaper <policy-name> class <class ID> ceiling <rate>` + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. - Available suffixes: - * % (percentage of total bandwidth) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority <value> -* 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. + 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). - :code:`set traffic-policy shaper <policy-name> class <class ID> - priority <priority>` + -* Set a queue length limit in packets: +Network emulator +---------------- - :code:`set traffic-policy shaper <policy name> class <class ID> queue-limit - <limit>` +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. -* Specify a queue type for a traffic class, default fair-queue. Available - queue types: +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. - * drop-tail - * fair-queue - * random-detect - * priority +This could be helpful if you want to test how an application behaves +under certain network conditions. - :code:`set traffic-policy shaper <policy name> class <class ID> queue-type <type>` -* 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: +.. 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. - :code:`set traffic-policy shaper <policy name> class <class ID> set-dscp <value>` +.. 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. - DSCP values as per :rfc:`2474` and :rfc:`4595`: +.. 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. - +---------+------------+--------+------------------------------+ - | 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> 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. -Matching rules -************** +.. 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. -* Define a class matching rule: +.. 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. - :code:`set traffic-policy shaper <policy name> class <class ID> match - <match name>` +.. 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. -* Add a match rule description: - :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 - https://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' +.. _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) -.. _TBF: https://en.wikipedia.org/wiki/Token_bucket +.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket .. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve .. _IFB: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/services/console-server.rst b/docs/services/console-server.rst new file mode 100644 index 00000000..248def3b --- /dev/null +++ b/docs/services/console-server.rst @@ -0,0 +1,188 @@ +.. _console_server: + +############## +Console-Server +############## + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +Setup +===== + +In the past serial interface have been defined as ttySx and ttyUSBx where x was +an instance number of the serial interface. It was discovered that from system +boot to system boot the mapping of USB based serial interfaces will differ, +depending which driver was loaded first by the operating system. This will become +rather painful if you not only have serial interfaces for a console server +connected but in addition also a serial backed :ref:`wwan-interface`. + +To overcome this issue and the fact that in almost 50% of all cheap USB to serial +converters there is no serial number programmed, the USB to serial interface is +now directly identified by the USB root bridge and bus it connects to. This +somehow mimics the new network interface definitions we see in recend Linux +distributions. + +For additional details you can refer to https://phabricator.vyos.net/T2490. + +.. opcmd:: show system usb + + Retrieve a tree like representation of all connected USB devices. + + .. note:: If a device is unplugged and re-plugged it will receive a new + Port, Dev, If identification. + + .. code-block:: none + + vyos@vyos:~$ show system usb + /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M + /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M + /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + + +.. opcmd:: show system usb + + Retrieve a list and description of all connected USB serial devices. The device name + displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing the serial console + as console-server device. + + .. code-block:: none + + vyos@vyos$ show system usb serial + Device Model Vendor + ------ ------ ------ + usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. + usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. + usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + + +Configuration +============= + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +.. cfgcmd:: service console-server <device> data-bits + + Configure either seven or eight data bits. This defaults to eight data + bits if left unconfigured. + +.. cfgcmd:: service console-server <device> description + + A user friendly description identifying the connected peripheral. + +.. cfgcmd:: service console-server <device> parity [even | odd | none] + + Set the parity option for the console. If unset this will default to none. + +.. cfgcmd:: service console-server <device> stop-bits + + Configure either one or two stop bits. This defaults to one stop bits if + left unconfigured. + +.. cfgcmd:: service console-server <device> speed <baudrate> + + .. note:: USB to serial converters will handle most of their work in software + so you should be carefull with the selected baudrate as some times they + can't cope with the expected speed. + +Remote Access +------------- + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +.. cfgcmd:: service console-server <device> ssh port <port> + + Accept SSH connections for the given `<device>` on TCP port `<port>`. + After successfull authentication the user will be directly dropped to + the connected serial device. + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + +Operation +========= + +.. opcmd:: show console-server ports + + Show configured serial ports and their respective interface configuration. + + .. code-block:: none + + vyos@vyos:~$ show console-server ports + usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n + +.. opcmd:: show console-server user + + Show currently connected users. + + .. code-block:: + + vyos@vyos:~$ show console-server user + usb0b2.4p1.0 up vyos@localhost + + +.. opcmd:: connect console-server <device> + + Locally connect to serial port identified by `<device>`. + + .. code-block:: none + + vyos@vyos-r1:~$ connect console-server usb0b2.4p1.0 + [Enter `^Ec?' for help] + [-- MOTD -- VyOS Console Server] + + vyos-r2 login: + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + + .. hint:: The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit + the session use: ``Ctrl+E c .`` diff --git a/docs/services/index.rst b/docs/services/index.rst index cc6b96ae..76520b52 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -10,6 +10,7 @@ This chapter describes the available system/network services provided by VyOS. :maxdepth: 1 conntrack + console-server dhcp dns-forwarding dynamic-dns |
