From 0abea04850dfdaa0b56fc6dec94e5303300ba712 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:18:33 +0100 Subject: arrange firewall --- docs/configuration/firewall/index.rst | 767 ++++++++++++++++++++++++++++++++++ docs/configuration/index.rst | 23 + 2 files changed, 790 insertions(+) create mode 100644 docs/configuration/firewall/index.rst create mode 100644 docs/configuration/index.rst (limited to 'docs/configuration') diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst new file mode 100644 index 00000000..870e9a08 --- /dev/null +++ b/docs/configuration/firewall/index.rst @@ -0,0 +1,767 @@ +.. _firewall: + +Firewall +======== + +Overview +-------- + +VyOS makes use of Linux `netfilter `_ for packet +filtering. + +The firewall supports the creation of groups for ports, addresses, and +networks (implemented using netfilter ipset) and the option of interface +or zone based firewall policy. + +.. note:: **Important note on usage of terms:** + The firewall makes use of the terms `in`, `out`, and `local` + for firewall policy. Users experienced with netfilter often confuse + `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` + chain from netfilter. This is not the case. These instead indicate + the use of the `FORWARD` chain and either the input or output + interface. The `INPUT` chain, which is used for local traffic to the + OS, is a reference to as `local` with respect to its input interface. + + +Global settings +--------------- + +Some firewall settings are global and have a affect on the whole system. + +.. cfgcmd:: set firewall all-ping [enable | disable] + + By default, when VyOS receives an ICMP echo request packet destined for + itself, it will answer with an ICMP echo reply, unless you avoid it + through its firewall. + + With the firewall you can set rules to accept, drop or reject ICMP in, + out or local traffic. You can also use the general **firewall all-ping** + command. This command affects only to LOCAL (packets destined for your + VyOS system), not to IN or OUT traffic. + + .. note:: **firewall all-ping** affects only to LOCAL and it always + behaves in the most restrictive way + + .. code-block:: none + + set firewall all-ping enable + + When the command above is set, VyOS will answer every ICMP echo request + addressed to itself, but that will only happen if no other rule is + applied dropping or rejecting local echo requests. In case of conflict, + VyOS will not answer ICMP echo requests. + + .. code-block:: none + + set firewall all-ping disable + + When the command above is set, VyOS will answer no ICMP echo request + addressed to itself at all, no matter where it comes from or whether + more specific rules are being applied to accept them. + +.. cfgcmd:: set firewall broadcast-ping [enable | disable] + + This setting enable or disable the response of icmp broadcast + messages. The following system parameter will be altered: + + * ``net.ipv4.icmp_echo_ignore_broadcasts`` + +.. cfgcmd:: set firewall ip-src-route [enable | disable] +.. cfgcmd:: set firewall ipv6-src-route [enable | disable] + + This setting handle if VyOS accept packets with a source route + option. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_source_route`` + * ``net.ipv6.conf.all.accept_source_route`` + +.. cfgcmd:: set firewall receive-redirects [enable | disable] +.. cfgcmd:: set firewall ipv6-receive-redirects [enable | disable] + + enable or disable of ICMPv4 or ICMPv6 redirect messages accepted + by VyOS. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_redirects`` + * ``net.ipv6.conf.all.accept_redirects`` + +.. cfgcmd:: set firewall send-redirects [enable | disable] + + enable or disable of ICMPv4 redirect messages send by VyOS + The following system parameter will be altered: + + * ``net.ipv4.conf.all.send_redirects`` + +.. cfgcmd:: set firewall log-martians [enable | disable] + + enable or disable the logging of martian IPv4 packets. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.log_martians`` + +.. cfgcmd:: set firewall source-validation [strict | loose | disable] + + Set the IPv4 source validation mode. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.rp_filter`` + +.. cfgcmd:: set firewall syn-cookies [enable | disable] + + Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + The following system parameter will be altered: + + * ``net.ipv4.tcp_syncookies`` + +.. cfgcmd:: set firewall twa-hazards-protection [enable | disable] + + Enable or Disable VyOS to be :rfc:`1337` conform. + The following system parameter will be altered: + + * ``net.ipv4.tcp_rfc1337`` + +.. cfgcmd:: set firewall state-policy established action [accept | drop | + reject] + +.. cfgcmd:: set firewall state-policy established log enable + + Set the global setting for a astablished connections. + +.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy invalid log enable + + Set the global setting for invalid packets. + +.. cfgcmd:: set firewall state-policy related action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy related log enable + + Set the global setting for related connections. + + +Groups +------ + +Firewall groups represent collections of IP addresses, networks, or +ports. Once created, a group can be referenced by firewall rules as +either a source or destination. Members can be added or removed from a +group without changes to, or the need to reload, individual firewall +rules. + +.. note:: Groups can also be referenced by NAT configuration. + +Groups need to have unique names. Even though some contain IPv4 +addresses and others contain IPv6 addresses, they still need to have +unique names, so you may want to append "-v4" or "-v6" to your group +names. + + +Address Groups +************** + +In a **address group** a single IP adresses or IP address ranges are +definded. + +.. cfgcmd:: set firewall group address-group address [address | + address range] +.. cfgcmd:: set firewall group ipv6-address-group address
+ + Define a IPv4 or a IPv6 address group + + .. code-block:: none + + set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 + set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 + set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 + +.. cfgcmd:: set firewall group address-group description +.. cfgcmd:: set firewall group ipv6-address-group description + + Provide a IPv4 or IPv6 address group description + + +Network Groups +************** + +While **network groups** accept IP networks in CIDR notation, specific +IP addresses can be added as a 32-bit prefix. If you foresee the need +to add a mix of addresses and networks, the network group is +recommended. + +.. cfgcmd:: set firewall group network-group network +.. cfgcmd:: set firewall group ipv6-network-group network + + Define a IPv4 or IPv6 Network group. + + .. code-block:: none + + set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 + set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 + set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 + +.. cfgcmd:: set firewall group network-group description +.. cfgcmd:: set firewall group ipv6-network-group description + + Provide a IPv4 or IPv6 network group description. + + +Port Groups +*********** + +A **port group** represents only port numbers, not the protocol. Port +groups can be referenced for either TCP or UDP. It is recommended that +TCP and UDP groups are created separately to avoid accidentally +filtering unnecessary ports. Ranges of ports can be specified by using +`-`. + +.. cfgcmd:: set firewall group port-group port + [portname | portnumber | startport-endport] + + Define a port group. A port name are any name defined in + /etc/services. e.g.: http + + .. code-block:: none + + set firewall group port-group PORT-TCP-SERVER1 port http + set firewall group port-group PORT-TCP-SERVER1 port 443 + set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 + +.. cfgcmd:: set firewall group port-group description + + Provide a port group description. + + +Rule-Sets +---------- + +A rule-set is a named collection of firewall rules that can be applied +to an interface or zone. Each rule is numbered, has an action to apply +if the rule is matched, and the ability to specify the criteria to +match. Data packets go through the rules from 1 - 9999, at the first match +the action of the rule will executed. + +.. cfgcmd:: set firewall name description +.. cfgcmd:: set firewall ipv6-name description + + Provide a rule-set description. + +.. cfgcmd:: set firewall name default-action [drop | reject | accept] +.. cfgcmd:: set firewall ipv6-name default-action [drop | reject | + accept] + + This set the default action of the rule-set if no rule matched a paket + criteria. + +.. cfgcmd:: set firewall name enable-default-log +.. cfgcmd:: set firewall ipv6-name enable-default-log + + Use this command to enable the logging of the default action. + +.. cfgcmd:: set firewall name rule <1-9999> action [drop | reject | + accept] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> action [drop | reject | + accept] + + This required setting define the action of the current rule. + +.. cfgcmd:: set firewall name rule <1-9999> description +.. cfgcmd:: set firewall ipv6-name rule <1-9999> description + + Provide a description for each rule. + +.. cfgcmd:: set firewall name rule <1-9999> log [disable | enable] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> log [disable | enable] + + Enable or disable logging for the matched packet. + +.. cfgcmd:: set firewall name rule <1-9999> disable +.. cfgcmd:: set firewall ipv6-name rule <1-9999> disable + + If you want to disable a rule but let it in the configuration. + +Matching criteria +***************** + +There are a lot of matching criteria gainst which the package can be tested. + + +.. cfgcmd:: set firewall name rule <1-9999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall name rule <1-9999> destination address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination address + [address | addressrange | CIDR] + + This is similiar to the network groups part, but here you are able to negate + the matching addresses. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 100 source address 192.0.2.10-192.0.2.11 + # with a '!' the rule match everything except the specified subnet + set fitewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 + set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 + + +.. cfgcmd:: set firewall name rule <1-9999> source mac-address + +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source mac-address + + + Only in the source criteria you can specify a mac-address + + .. code-block:: none + + set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 + set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 + +.. cfgcmd:: set firewall name rule <1-9999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall name rule <1-9999> destination port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination port + [1-65535 | portname | start-end] + + A port can be set with a portnumber or a name which is here + defined: ``/etc/services``. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 source port '22' + set firewall name WAN-IN-v4 rule 11 source port '!http' + set firewall name WAN-IN-v4 rule 12 source port 'https' + + Multiple source ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + + .. code-block:: none + + set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' + +.. cfgcmd:: set firewall name rule <1-9999> source group + address-group +.. cfgcmd:: set firewall name rule <1-9999> destination group + address-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group + address-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group + address-group + + Use a specific address-group + +.. cfgcmd:: set firewall name rule <1-9999> source group + network-group +.. cfgcmd:: set firewall name rule <1-9999> destination group + network-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group + network-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group + network-group + + Use a specific network-group + +.. cfgcmd:: set firewall name rule <1-9999> source group + port-group +.. cfgcmd:: set firewall name rule <1-9999> destination group + port-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group + port-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group + port-group + + Use a specific port-group + +.. cfgcmd:: set firewall name rule <1-9999> protocol [ | + <0-255> | all | tcp_udp] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> protocol [ | + <0-255> | all | tcp_udp] + + Match a protocol criteria. A protocol number or a name which is here + defined: ``/etc/protocols``. + Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and upd + based pakets. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 protocol tcp_udp + set firewall name WAN-IN-v4 rule 11 protocol !tcp_udp + set firewall ipv6-name WAN-IN-v6 rule 10 protocol tcp + +.. cfgcmd:: set firewall name rule <1-9999> tcp flags +.. cfgcmd:: set firewall ipv6-name rule <1-9999> tcp flags + + Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, + ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma + separated. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' + set firewall name WAN-IN-v4 rule 12 tcp flags 'SYN' + set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' + +.. cfgcmd:: set firewall name rule <1-9999> state [established | + invalid | new | related] [enable | disable ] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> state [established | + invalid | new | related] [enable | disable ] + + Match against the state of a packet. + + +Applying a Rule-Set to an Interface +----------------------------------- + +A Rule-Set can be appliend to every inteface: + +* ``in``: Ruleset for forwarded packets on inbound interface +* ``out``: Ruleset for forwarded packets on outbound interface +* ``local``: Ruleset for packets destined for this router + +.. cfgcmd:: set interface ethernet firewall [in | out | local] + [name | ipv6-name] + + Here are some examples for applying a rule-set to an interface + + .. code-block:: none + + set interface ethernet eth1 vif 100 firewall in name LANv4-IN + set interface ethernet eth1 vif 100 firewall out name LANv4-OUT + set interface bonding bond0 firewall in name LANv4-IN + set interfaces openvpn vtun1 firewall in name Lanv4-IN + + .. note:: + As you can see in the example here, you can assign the same rule-set to + several interfaces. An interface can only have one rule-set per chain. + + +Zone-based Firewall Policy +-------------------------- + +As an alternative to applying policy to an interface directly, a +zone-based firewall can be created to simplify configuration when +multiple interfaces belong to the same security zone. Instead of +applying rulesets to interfaces, they are applied to source +zone-destination zone pairs. + +An basic introduction to zone-based firewalls can be found `here +`_, +and an example at :ref:`examples-zone-policy`. + +Define a Zone +************* + +To define a zone setup either one with interfaces or a local zone. + +.. cfgcmd:: set zone-policy zone interface + + Set a interfaces to a zone. A zone can have multiple interfaces. + But a interface can only be member in one zone. + +.. cfgcmd:: set zone-policy zone local-zone + + Define the Zone as a local zone. A local zone have no interfaces and + will be applied to the router itself. + +.. cfgcmd:: set zone-policy zone default-action [drop | reject] + + Change the default-action with this setting. + +.. cfgcmd:: set zone-policy zone description + + Set a meaningful description. + + +Applying a Rule-Set to a Zone +***************************** + +Before you are able to apply a rule-set to a zone you have to create the zones +first. + +.. cfgcmd:: set zone-policy zone from firewall name + +.. cfgcmd:: set zone-policy zone from firewall ipv6-name + + + You apply a rule-set always to a zone from a other zone, it is recommended + to create one rule-set for each zone pair. + + .. code-block:: none + + set zone-policy zone DMZ from LAN firewall name LANv4-to-DMZv4 + set zone-policy zone LAN from DMZ firewall name DMZv4-to-LANv4 + + +Operation-mode Firewall +----------------------- + +Rule-set overview +***************** + +.. opcmd:: show firewall + + This will show you a basic firewall overview + + .. code-block:: none + + vyos@vyos:~$ show firewall + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + established accept disabled + related accept disabled + + ----------------------------- + Rulesets Information + ----------------------------- + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-IN": + + Active on (eth0,IN) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept icmp 0 0 + condition - saddr 10.1.0.0/24 daddr 0.0.0.0/0 LOG enabled + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-OUT": + + Active on (eth0,OUT) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept tcp_udp 1 60 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 match-DST-PORT-GROUP DMZ-Ports /* + DMZv4-1-OUT-10 */LOG enabled + + 11 accept icmp 1 84 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* DMZv4-1-OUT-11 */LOG enabled + + 10000 drop all 6 360 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "LANv4-IN": + + Inactive - Not applied to any interfaces or zones. + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* LANv4-IN-10 */ + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 + +.. opcmd:: show firewall summary + + This will show you a summary about rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + related accept disabled + established accept disabled + + ------------------------ + Firewall Rulesets + ------------------------ + + IPv4 name: + + Rule-set name Description References + ------------- ----------- ---------- + DMZv4-1-OUT (eth0,OUT) + DMZv4-1-IN (eth0,IN) + + ------------------------ + Firewall Groups + ------------------------ + + Port Groups: + + Group name Description References + ---------- ----------- ---------- + DMZ-Ports DMZv4-1-OUT-10-destination + + Network Groups: + + Group name Description References + ---------- ----------- ---------- + LANv4 LANv4-IN-10-source, + DMZv4-1-OUT-10-source, + DMZv4-1-OUT-11-source + +.. opcmd:: show firewall statistics + + This will show you a statistic of all rule-sets since the last boot. + +.. opcmd:: show firewall [name | ipv6name] rule <1-9999> + + This command will give an overview about a rule in a single rule-set + +.. opcmd:: show firewall group + + Overview of defined groups. You see the type, the members, and where the + group is used. + + .. code-block:: none + + vyos@vyos:~$ show firewall group DMZ-Ports + Name : DMZ-Ports + Type : port + References : none + Members : + 80 + 443 + 8080 + 8443 + + vyos@vyos:~$ show firewall group LANv4 + Name : LANv4 + Type : network + References : LANv4-IN-10-source + Members : + 10.10.0.0/16 + +.. opcmd:: show firewall [name | ipv6name] + + This command will give an overview about a single rule-set + +.. opcmd:: show firewall [name | ipv6name] statistics + + This will show you a rule-set statistic since the last boot. + +.. opcmd:: show firewall [name | ipv6name] rule <1-9999> + + This command will give an overview about a rule in a single rule-set + + +Zone-Policy Overview +******************** + +.. opcmd:: show zone-policy zone + + Use this command to get an overview about a zone + + .. code-block:: none + + vyos@vyos:~$ show zone-policy zone DMZ + ------------------- + Name: DMZ + + Interfaces: eth0 eth1 + + From Zone: + name firewall + ---- -------- + LAN DMZv4-1-OUT + + +Show Firewall log +***************** + +.. opcmd:: show log firewall [name | ipv6name] + + Show the logs of a specific Rule-Set + +.. note:: + At the moment it not possible to look at the whole firewall log with VyOS + operational commands. All logs will save to ``/var/logs/messages``. + For example: ``grep '10.10.0.10' /var/log/messages`` + + + +Example Partial Config +---------------------- + +.. code-block:: none + + firewall { + all-ping enable + broadcast-ping disable + config-trap disable + group { + network-group BAD-NETWORKS { + network 198.51.100.0/24 + network 203.0.113.0/24 + } + network-group GOOD-NETWORKS { + network 192.0.2.0/24 + } + port-group BAD-PORTS { + port 65535 + } + } + name FROM-INTERNET { + default-action accept + description "From the Internet" + rule 10 { + action accept + description "Authorized Networks" + protocol all + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 11 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + rule 30 { + action drop + description "BAD PORTS" + destination { + group { + port-group BAD-PORTS + } + } + log enable + protocol all + } + } + } + interfaces { + ethernet eth1 { + address dhcp + description OUTSIDE + duplex auto + firewall { + in { + name FROM-INTERNET + } + } + } + } diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst new file mode 100644 index 00000000..bce013cb --- /dev/null +++ b/docs/configuration/index.rst @@ -0,0 +1,23 @@ +################### +Configuration Guide +################### + +The following structure respresent the cli structure. + +.. toctree:: + :maxdepth: 1 + :includehidden: + + firewall/index + highavailability/index + interfaces/index + loadbalancing/index + nat/index + policy/index + protocols/index + service/index + system/index + trafficpolicy/index + vpn/index + vrf/index + zonepolicy/index \ No newline at end of file -- cgit v1.2.3 From bfb3814cd120d1bb661af26b3c55341f1697b397 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:25:50 +0100 Subject: arrange loadbalancing, high availability, qos --- docs/configuration/highavailability/index.rst | 158 ++++ docs/configuration/loadbalancing/index.rst | 263 ++++++ docs/configuration/trafficpolicy/index.rst | 1202 +++++++++++++++++++++++++ docs/high-availability.rst | 158 ---- docs/load-balancing.rst | 263 ------ docs/qos.rst | 1197 ------------------------ 6 files changed, 1623 insertions(+), 1618 deletions(-) create mode 100644 docs/configuration/highavailability/index.rst create mode 100644 docs/configuration/loadbalancing/index.rst create mode 100644 docs/configuration/trafficpolicy/index.rst delete mode 100644 docs/high-availability.rst delete mode 100644 docs/load-balancing.rst delete mode 100644 docs/qos.rst (limited to 'docs/configuration') diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst new file mode 100644 index 00000000..ad714597 --- /dev/null +++ b/docs/configuration/highavailability/index.rst @@ -0,0 +1,158 @@ +.. _high-availability: + +High availability +================= + +VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers. +Every VRRP router has a physical IP/IPv6 address, and a virtual address. +On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. +If the master fails and stops sending keepalive packets, the router with the next highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. +You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). +If you setup multiple groups on the same interface, their VRIDs must be unique, but it's possible (even if not recommended for readability reasons) to use duplicate VRIDs on different interfaces. + +Basic setup +----------- + +VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. +The required parameters are interface, vrid, and virtual-address. + +minimal config + +.. code-block:: none + + set high-availability vrrp group Foo vrid 10 + set high-availability vrrp group Foo interface eth0 + set high-availability vrrp group Foo virtual-address 192.0.2.1/24 + +You can verify your VRRP group status with the operational mode ``run show vrrp`` command: + +.. code-block:: none + + vyos@vyos# run show vrrp + Name Interface VRID State Last Transition + ---------- ----------- ------ ------- ----------------- + Foo eth1 10 MASTER 2s + +IPv6 support +------------ + +The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you cannot mix IPv4 and IPv6 in the same group, and will need to create groups with different VRIDs specially for IPv4 and IPv6. + +Disabling a VRRP group +---------------------- + +You can disable a VRRP group with ``disable`` option: + +.. code-block:: none + + set high-availability vrrp group Foo disable + +A disabled group will be removed from the VRRP process and your router will not participate in VRRP for that VRID. It will disappear from operational mode commands output, rather than enter the backup state. + +Setting VRRP group priority +--------------------------- + +VRRP priority can be set with ``priority`` option: + +.. code-block:: none + + set high-availability vrrp group Foo priority 200 + +The priority must be an integer number from 1 to 255. Higher priority value increases router's precedence in the master elections. + +Sync groups +----------- + +A sync group allows VRRP groups to transition together. + +.. code-block:: none + + edit high-availability vrrp + set sync-group MAIN member VLAN9 + set sync-group MAIN member VLAN20 + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +.. code-block:: none + + vrrp { + group VLAN9 { + interface eth0.9 + virtual-address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + virtual-address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } + } + + +.. warning:: All items in a sync group should be similarly configured. If one VRRP group is set to a different premption delay or priority, it would result in an endless transition loop. + + +Preemption +---------- + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" option: + +.. code-block:: none + + set high-availability vrrp group Foo no-preempt + +You can also configure the time interval for preemption with the "preempt-delay" option. For example, to set the higher priority router to take over in 180 seconds, use: + +.. code-block:: none + + set high-availability vrrp group Foo preempt-delay 180 + +Unicast VRRP +------------ + +By default VRRP uses multicast packets. If your network does not support multicast for whatever reason, you can make VRRP use unicast communication instead. + +.. code-block:: none + + set high-availability vrrp group Foo peer-address 192.0.2.10 + set high-availability vrrp group Foo hello-source-address 192.0.2.15 + +Scripting +--------- + +VRRP functionality can be extended with scripts. VyOS supports two kinds of scripts: health check scripts and transition scripts. Health check scripts execute custom checks in addition to the master router reachability. +Transition scripts are executed when VRRP state changes from master to backup or fault and vice versa and can be used to enable or disable certain services, for example. + +Health check scripts +^^^^^^^^^^^^^^^^^^^^ + +This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: + +.. code-block:: none + + set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh + set high-availability vrrp group Foo health-check interval 60 + set high-availability vrrp group Foo health-check failure-count 3 + +Transition scripts +^^^^^^^^^^^^^^^^^^ + +Transition scripts can help you implement various fixups, such as starting and stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: + +.. code-block:: none + + set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst new file mode 100644 index 00000000..6b0bede9 --- /dev/null +++ b/docs/configuration/loadbalancing/index.rst @@ -0,0 +1,263 @@ +.. _load-balancing: + +WAN load balancing +================== + +Outbound traffic can be balanced between two or more outbound interfaces. +If a path fails, traffic is balanced across the remaining healthy paths, a recovered path is automatically added back to the routing table and used by the load balancer. +The load balancer automatically adds routes for each path to the routing table and balances traffic across the configured interfaces, determined by interface health and weight. + + +In a minimal, configuration the following must be provided: + + * a interface with a nexthop + * one rule with a LAN (inbound-interface) and the WAN (interface). + +Let's assume we have two DHCP WAN interfaces and one LAN (eth2): + +.. code-block:: none + + set load-balancing wan interface-health eth0 nexthop 'dhcp' + set load-balancing wan interface-health eth1 nexthop 'dhcp' + set load-balancing wan rule 1 inbound-interface 'eth2' + set load-balancing wan rule 1 interface eth0 + set load-balancing wan rule 1 interface eth1 + +Balancing Rules +--------------- + +Interfaces, their weight and the type of traffic to be balanced are defined in numbered balancing rule sets. +The rule sets are executed in numerical order against outgoing packets. In case of a match the packet is sent through an interface specified in the matching rule. +If a packet doesn't match any rule it is sent by using the system routing table. Rule numbers can't be changed. + +Create a load balancing rule, rule can be a number between 1 and 9999: + +.. code-block:: none + + vyos@vyos# set load-balancing wan rule 1 + Possible completions: + description Description for this rule + > destination Destination + exclude Exclude packets matching this rule from wan load balance + failover Enable failover for packets matching this rule from wan load balance + inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] + +> interface Interface name [REQUIRED] + > limit Enable packet limit for this rule + per-packet-balancing Option to match traffic per-packet instead of the default, per-flow + protocol Protocol to match + > source Source information + +Interface weight +**************** + +Let's expand the example from above and add a weight to the interfaces. The bandwidth from eth0 is larger than eth1. +Per default outbound traffic is distributed randomly across available interfaces. Weights can be assigned to interfaces to influence the balancing. + +.. code-block:: none + + set load-balancing wan rule 1 interface eth0 weight 2 + set load-balancing wan rule 1 interface eth1 weight 1 + +66% traffic is routed to eth0 and eth1 get 33% of traffic. + +Rate limit +********** + +A packet rate limit can be set for a rule to apply the rule to traffic above or below a specified threshold. +To configure the rate limiting use: + +.. code-block:: none + + set load-balancing wan rule limit + +* ``burst``: Number of packets allowed to overshoot the limit within ``period``. Default 5. +* ``period``: Time window for rate calculation. Possible values: ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). Default is ``second``. +* ``rate``: Number of packets. Default 5. +* ``threshold``: ``below`` or ``above`` the specified rate limit. + +Flow and packet-based balancing +******************************* + +Outgoing traffic is balanced in a flow-based manner. +A connection tracking table is used to track flows by their source address, destination address and port. +Each flow is assigned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. +This has the advantage that packets always arrive in order if links with different speeds are in use. + +Packet-based balancing can lead to a better balance across interfaces when out of order packets are no issue. Per-packet-based balancing can be set for a balancing rule with: + +.. code-block:: none + + set load-balancing wan rule per-packet-balancing + +Exclude traffic +*************** + +To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: + +.. code-block:: none + + set load-balancing wan rule exclude + + +Health checks +------------- + +The health of interfaces and paths assigned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. +If an interface fails the health check it is removed from the load balancer's pool of interfaces. To enable health checking for an interface: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health + Possible completions: + failure-count Failure count + nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] + success-count Success count + +> test Rule number + +Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` + +.. code-block:: none + + set load-balancing wan interface-health nexthop + +Set the number of health check failures before an interface is marked as unavailable, range for number is 1 to 10, default 1. +Or set the number of successful health checks before an interface is added back to the interface pool, range for number is 1 to 10, default 1. + +.. code-block:: none + + set load-balancing wan interface-health failure-count + set load-balancing wan interface-health success-count + +Each health check is configured in its own test, tests are numbered and processed in numeric order. +For multi target health checking multiple tests can be defined: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health eth1 test 0 + Possible completions: + resp-time Ping response time (seconds) + target Health target address + test-script Path to user defined script + ttl-limit Ttl limit (hop count) + type WLB test type + +* ``resp-time``: the maximum response time for ping in seconds. Range 1...30, default 5 +* ``target``: the target to be sent ICMP packets to, address can be an IPv4 address or hostname +* ``test-script``: A user defined script must return 0 to be considered successful and non-zero to fail. Scripts are located in /config/scripts, for different locations the full path needs to be provided +* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be specified. The limit must be shorter than the path length, an ICMP time expired message is needed to be returned for a successful test. default 1 +* ``type``: Specify the type of test. type can be ping, ttl or a user defined script + +Source NAT rules +---------------- + +Per default, interfaces used in a load balancing pool replace the source IP of each outgoing packet with its own address to ensure that replies arrive on the same interface. +This works through automatically generated source NAT (SNAT) rules, these rules are only applied to balanced traffic. In cases where this behaviour is not desired, the automatic generation of SNAT rules can be disabled: + +.. code-block:: none + + set load-balancing wan disable-source-nat + +Sticky Connections +------------------ +Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. + +.. image:: /_static/images/sticky-connections.jpg + :width: 80% + :align: center + + +Upon reception of an incoming packet, when a response is sent, it might be desired to ensure that it leaves from the same interface as the inbound one. +This can be achieved by enabling sticky connections in the load balancing: + +.. code-block:: none + + set load-balancing wan sticky-connections inbound + +Failover +-------- + +In failover mode, one interface is set to be the primary interface and other interfaces are secondary or spare. +Instead of balancing traffic across all healthy interfaces, only the primary interface is used and in case of failure, a secondary interface selected from the pool of available interfaces takes over. +The primary interface is selected based on its weight and health, others become secondary interfaces. +Secondary interfaces to take over a failed primary interface are chosen from the load balancer's interface pool, depending on their weight and health. +Interface roles can also be selected based on rule order by including interfaces in balancing rules and ordering those rules accordingly. To put the load balancer in failover mode, create a failover rule: + +.. code-block:: none + + set load-balancing wan rule failover + +Because existing sessions do not automatically fail over to a new path, the session table can be flushed on each connection state change: + +.. code-block:: none + + set load-balancing wan flush-connections + +.. warning:: + + Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. + +Script execution +---------------- + +A script can be run when an interface state change occurs. Scripts are run from /config/scripts, for a different location specify the full path: + +.. code-block:: none + + set load-balancing wan hook script-name + +Two environment variables are available: + +* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored +* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state + +.. warning:: + + Blocking call with no timeout. System will become unresponsive if script does not return! + +Handling and monitoring +----------------------- + + +Show WAN load balancer information including test types and targets. +A character at the start of each line depicts the state of the test + +* ``+`` successful +* ``-`` failed +* a blank indicates that no test has been carried out + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance + Interface: eth0 + Status: failed + Last Status Change: Tue Jun 11 20:12:19 2019 + -Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + + Interface: eth1 + Status: active + Last Status Change: Tue Jun 11 20:06:42 2019 + +Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 + +Show connection data of load balanced traffic: + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance connection + conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. + Type State Src Dst Packets Bytes + tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 + udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 + udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 + +Restart +******* + +.. code-block:: none + + restart wan-load-balance diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst new file mode 100644 index 00000000..babccd6f --- /dev/null +++ b/docs/configuration/trafficpolicy/index.rst @@ -0,0 +1,1202 @@ +.. _qos: + +############## +Traffic Policy +############## + + +*** +QoS +*** + +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. + +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. + + +How to make it work +=================== + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + + 1. **Create a traffic policy**. + + 2. **Apply the traffic policy to an interface ingress or egress**. + + +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. + + +Units +===== + +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. + +Prefixes +-------- + +They can be **decimal** prefixes. + + .. code-block:: none + + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second + +Or **binary** prefixes. + + .. code-block:: none + + kibit (2^10 = 1024) kibibit per second + mibit (2^20 = 1024^2) mebibit per second + gibit (2^30 = 1024^3) gibibit per second + tbit (2^40 = 1024^4) tebibit per second + + kibps (1024*8) kibibyte (KiB) per second + mibps (1024^2*8) mebibyte (MiB) per second + gibps (1024^3*8) gibibyte (GiB) per second + tibps (1024^4*8) tebibyte (TiB) per second + + +Suffixes +-------- + +A *bit* is written as **bit**, + + .. code-block:: none + + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) + +while a *byte* is written as a single **b**. + + .. code-block:: none + + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) + + + + +.. _classes: + +Classes +======= + +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. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + + +Matching traffic +---------------- + +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. + +In VyOS, a class is identified by a number you can choose when +configuring it. + + +.. 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-block:: none + + set traffic-policy class match + + +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. + +A class can have multiple match filters: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs + +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. + +For example: + +.. code-block:: none + + 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 + +This will match TCP traffic with source port 80. + +There are many parameters you will be able to use in order to match the +traffic you want for a class: + + - **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** + +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. + + +.. code-block:: none + + 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 + + + +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`_. + +You can also write a description for a filter: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" + + + +.. note:: An IPv4 TCP filter will only match packets with an IPv4 header length of + 20 bytes (which is the majority of IPv4 packets anyway). + + +.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see + https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers + + +Default +------- + +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. + + +Class treatment +--------------- + +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. + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + +For instance, with :code:`set traffic-policy shaper MY-SHAPER class 30 set-dscp EF` +you would be modifying the DSCP field value of packets in that class to +Expedite Forwarding. + + + DSCP values as per :rfc:`2474` and :rfc:`4595`: + + +---------+------------+--------+------------------------------+ + | 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 | + +---------+------------+--------+------------------------------+ + + + + +.. _embed: + +Embedding one policy into another one +------------------------------------- + +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. + +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 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. + +You can configure a policy into a class through the ``queue-type`` +setting. + +.. code-block:: none + + set traffic-policy shaper FQ-SHAPER bandwidth 4gbit + set traffic-policy shaper FQ-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-SHAPER default queue-type fq-codel + +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. + +.. note:: Some policies already include other embedded policies inside. + That is the case of Shaper_: each of its classes use fair-queue + unless you change it. + +.. _creating_a_traffic_policy: + + +Creating a traffic policy +========================= + +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). + +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. + +.. hint:: **If you are looking for a policy for your outbound traffic** + but you don't know which one you need and you don't want to go + through every possible policy shown here, **our bet is that highly + likely you are looking for a** Shaper_ **policy and you want to** + :ref:`set its queues ` **as FQ-CoDel**. + +Drop Tail +--------- + +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. + +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. + +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. + +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. + +This is the policy that requieres the lowest resources for the same +amount of traffic. But **very likely you do not need it as you cannot +get much from it. Sometimes it is used just to enable logging.** + +.. cfgcmd:: set traffic-policy drop-tail queue-limit + + 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). + + +Fair Queue +---------- + +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. + +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, that is, it balances traffic +distributing it through different sub-queues in order to ensure +fairness so that each flow is able to send data in turn, preventing any +single one from drowning out the rest. + + +.. cfgcmd:: set traffic-policy fair-queue + + 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. + +In order to separate traffic, Fair Queue uses a classifier based on +source address, destination address and source port. The algorithm +enqueues packets to hash buckets based on those tree parameters. +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. + +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. + +.. cfgcmd:: set traffic-policy fair-queue hash-interval ` + + 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). + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +.. cfgcmd:: set traffic-policy fair-queue queue-limit + + 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. + +.. 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. + + + +.. _FQ-CoDel: + +FQ-CoDel +-------- + +| **Queueing discipline** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. + +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. + +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. + +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. + +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. + + +.. 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. + + +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. + +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. + +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. + +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. + +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. + + +.. cfgcmd:: set traffic-policy fq-codel codel-quantum + + 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. + +.. cfgcmd:: set traffic-policy fq-codel flows + + 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. + +.. cfgcmd:: set traffic-policy fq-codel interval + + 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). + +.. cfgcmd:: set traffic-policy fq-codel queue-limit ` + + 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). + +.. cfgcmd:: set traffic-policy fq-codel target ` + + 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). + + +Example +^^^^^^^ + +A simple example of an FQ-CoDel policy working inside a Shaper one. + + +.. code-block:: none + + set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit + set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel + + + +Limiter +------- + +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. + +Limiter is one of those policies that uses classes_ (Ingress qdisc is +actually a classless policy but filters do work in it). + +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. + +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. + + +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. + + +.. cfgcmd:: set traffic-policy limiter class match description + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), a class matching rule name and its + description. + + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + + +.. cfgcmd:: set traffic-policy limiter class bandwidth + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the maximum allowed bandwidth for + this class. + + +.. cfgcmd:: set traffic-policy limiter class burst + + 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). + + +.. cfgcmd:: set traffic-policy limiter default bandwidth + + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. + + +.. cfgcmd:: set traffic-policy limiter default burst + + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. + + +.. cfgcmd:: set traffic-policy limiter class 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). + + + +Network Emulator +---------------- + +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. + +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. + +This could be helpful if you want to test how an application behaves +under certain network conditions. + + +.. cfgcmd:: set traffic-policy network-emulator bandwidth + + Use this command to configure the maximum rate at which traffic will + be shaped in a Network Emulator policy. Define the name of the policy + and the rate. + +.. cfgcmd:: set traffic-policy network-emulator burst + + 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 be configured through the + Token Bucket Filter qdisc). Default:15kb. It will only take effect if + you have configured its bandwidth too. + +.. cfgcmd:: set traffic-policy network-emulator network-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. The latency will be added through the + Token Bucket Filter qdisc. It will only take effect if you have + configured its bandwidth too. You can use secs, ms and us. Default: + 50ms. + +.. cfgcmd:: set traffic-policy network-emulator packet-corruption + + 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. + +.. cfgcmd:: set traffic-policy network-emulator packet-loss ` + + 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. + +.. cfgcmd:: set traffic-policy network-emulator packet-reordering ` + + Use this command to emulate packet-reordering conditions in a Network + Emulator policy. Set the policy name and the percentage of reordered + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator queue-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. + + + +Priority Queue +-------------- + +| **Queueing discipline:** PRIO. +| **Applies to:** Outbound traffic. + + +The Priority Queue is a classful scheduling policy. It does not delay +packets (Priority Queue is not a shaping policy), it simply dequeues +packets according to their priority. + +.. 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. + +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. + + +.. 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. + + +As with other policies, you can define different type of matching rules +for your classes: + +.. code-block:: none + + 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 + + +As with other policies, you can embed_ other policies into the classes +(and default) of your Priority Queue policy through the ``queue-type`` +setting: + +.. code-block:: none + + 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) + + +.. cfgcmd:: set traffic-policy priority-queue class queue-limit ` + + 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. + + + +.. _Random-Detect: + +Random-Detect +------------- + + +| **Queueing discipline:** Generalized Random Early Drop. +| **Applies to:** Outbound traffic. + +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. + +In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random +Early Detect policy that provides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. + +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. + +IP precedence 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 | + +------------+----------------------+ + + +Random-Detect could be useful for heavy traffic. One use of this +algorithm might be to prevent a backbone overload. But only for TCP +(because dropped packets could be retransmitted), not for UDP. + + +.. cfgcmd:: set traffic-policy random-detect bandwidth + + Use this command to configure a Random-Detect policy, set its name + and set the available bandwidth for this policy. It is used for + calculating the average queue size after some idle time. It should be + set to the bandwidth of your interface. Random Detect is not a + shaping policy, this command will not shape. + +.. cfgcmd:: set traffic-policy random-detect precedence average-packet + + 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). + +.. note:: When configuring a Random-Detect policy: **the higher the + precedence number, the higher the priority**. + +.. cfgcmd:: set traffic-policy random-detect precedence mark-probability + + 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). + + +.. cfgcmd:: set traffic-policy random-detect precedence maximum-threshold + + 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. + +.. cfgcmd:: set traffic-policy random-detect precedence minimum-threshold + + 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. + + +The default values for the minimum-threshold depend on IP precedence: + + +------------+-----------------------+ + | Precedence | default min-threshold | + +============+=======================+ + | 7 | 16 | + +------------+-----------------------+ + | 6 | 15 | + +------------+-----------------------+ + | 5 | 14 | + +------------+-----------------------+ + | 4 | 13 | + +------------+-----------------------+ + | 3 | 12 | + +------------+-----------------------+ + | 2 | 11 | + +------------+-----------------------+ + | 1 | 10 | + +------------+-----------------------+ + | 0 | 9 | + +------------+-----------------------+ + + +.. cfgcmd:: set traffic-policy random-detect precedence queue-limit + + 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. + + +If the average queue size is lower than the **min-threshold**, an +arriving packet will be placed in the queue. + +In the case the average queue size is between **min-threshold** and +**max-threshold**, then an arriving packet would be either dropped or +placed in the queue, it will depend on the defined **mark-probability**. + +If the current queue size is larger than **queue-limit**, +then packets will be dropped. The average queue size depends on its +former average size and its current one. + +If **max-threshold** is set but **min-threshold is not, then +**min-threshold** is scaled to 50% of **max-threshold**. + +In principle, values must be +:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. + + + + +Rate Control +------------ + +| **Queueing discipline:** Tocken Bucket Filter. +| **Applies to:** Outbound traffic. + +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. + +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. + +.. cfgcmd:: set traffic-policy rate-control bandwidth + + Use this command to configure a Rate-Control policy, set its name + and the rate limit you want to have. + +.. cfgcmd:: set traffic-policy rate-control burst + + 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. + + +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. + +A very small buffer will soon start dropping packets. + +.. cfgcmd:: set traffic-policy rate-control latency + + 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). + + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. + +.. _DRR: + +Round Robin +----------- + +| **Queueing discipline:** Deficit Round Robin. +| **Applies to:** Outbound traffic. + +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. + +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. + + +.. cfgcmd:: set traffic-policy round-robin class + quantum + + 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. + +.. cfgcmd:: set traffic-policy round-robin class + queue-limit + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the queue size in packets. + +As with other policies, Round-Robin can embed_ another policy into a +class through the ``queue-type`` setting. + +.. code-block:: none + + 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 + + + + +.. _Shaper: + +Shaper +------ + +| **Queueing discipline:** Hierarchical Token Bucket. +| **Applies to:** Outbound traffic. + + +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. + +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. + +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. + + +.. cfgcmd:: set traffic-policy shaper bandwidth + + Use this command to configure a Shaper policy, set its name + and the maximum bandwidth for all combined traffic. + + +.. cfgcmd:: set traffic-policy shaper class bandwidth + + 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. + +.. cfgcmd:: set traffic-policy shaper class burst + + 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 ceiling speed (default: 15Kb). + +.. cfgcmd:: set traffic-policy shaper class ceiling + + 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. + +.. cfgcmd:: set traffic-policy shaper class priority <0-7> + + 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. + + +As with other policies, Shaper can embed_ other policies into its +classes through the ``queue-type`` setting and then configure their +parameters. + + +.. code-block:: none + + 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) + + +.. code-block:: none + + 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) + + + +.. note:: If you configure a class for **VoIP traffic**, don't give it any + *ceiling*, otherwise new VoIP calls could start when the link is + available and get suddenly dropped when other classes start using + their assigned *bandwidth* share. + + +Example +^^^^^^^ + +A simple example of Shaper using priorities. + + +.. code-block:: none + + set traffic-policy shaper MY-HTB bandwidth '50mbit' + set traffic-policy shaper MY-HTB class 10 bandwidth '20%' + set traffic-policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' + set traffic-policy shaper MY-HTB class 10 queue-type 'fq-codel' + 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 PORT666 ip destination port '666' + 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' + + +Applying a traffic policy +========================= + +Once a traffic-policy is created, you can apply it to an interface: + +.. code-block:: none + + set interfaces etherhet eth0 traffic-policy out WAN-OUT + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +.. code-block:: none + + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + set interfaces etherhet eth1 traffic-policy in LAN-IN + set interfaces etherhet eth1 traffic-policy out LAN-OUT + set interfaces ethernet eth2 traffic-policy in LAN-IN + set interfaces ethernet eth2 traffic-policy out LAN-OUT + set interfaces etherhet eth3 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth3 traffic-policy out TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy out TWO-WAY-POLICY + +Getting queueing information +---------------------------- + +.. opcmd:: show queueing + + Use this command to see the queueing information for an interface. + You will be able to see a packet counter (Sent, Dropped, Overlimit + and Backlog) per policy and class configured. + + + +.. _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. You cannot apply a shaping +policy directly to the ingress traffic of any interface because shaping +only works for outbound traffic. + +This workaround lets you apply a shaping policy to the ingress traffic +by first redirecting it to an in-between virtual interface +(`Intermediate Functional Block`_). There, in that virtual interface, +you will be able to apply any of the policies that work for outbound +traffic, for instance, a shaping one. + +That is how it is possible to do the so-called "ingress shaping". + + +.. code-block:: none + + 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 + +.. warning:: + + Do not configure IFB as the first step. First create everything else + of your traffic-policy, and then you can configure IFB. + Otherwise you might get the ``RTNETLINK answer: File exists`` error, + which can be solved with ``sudo ip link delete ifb0``. + + +.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) +.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket +.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve +.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/high-availability.rst b/docs/high-availability.rst deleted file mode 100644 index ad714597..00000000 --- a/docs/high-availability.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. _high-availability: - -High availability -================= - -VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers. -Every VRRP router has a physical IP/IPv6 address, and a virtual address. -On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. -All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. -If the master fails and stops sending keepalive packets, the router with the next highest priority becomes the new master and takes over the virtual address. - -VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. -You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). -If you setup multiple groups on the same interface, their VRIDs must be unique, but it's possible (even if not recommended for readability reasons) to use duplicate VRIDs on different interfaces. - -Basic setup ------------ - -VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. -The required parameters are interface, vrid, and virtual-address. - -minimal config - -.. code-block:: none - - set high-availability vrrp group Foo vrid 10 - set high-availability vrrp group Foo interface eth0 - set high-availability vrrp group Foo virtual-address 192.0.2.1/24 - -You can verify your VRRP group status with the operational mode ``run show vrrp`` command: - -.. code-block:: none - - vyos@vyos# run show vrrp - Name Interface VRID State Last Transition - ---------- ----------- ------ ------- ----------------- - Foo eth1 10 MASTER 2s - -IPv6 support ------------- - -The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you cannot mix IPv4 and IPv6 in the same group, and will need to create groups with different VRIDs specially for IPv4 and IPv6. - -Disabling a VRRP group ----------------------- - -You can disable a VRRP group with ``disable`` option: - -.. code-block:: none - - set high-availability vrrp group Foo disable - -A disabled group will be removed from the VRRP process and your router will not participate in VRRP for that VRID. It will disappear from operational mode commands output, rather than enter the backup state. - -Setting VRRP group priority ---------------------------- - -VRRP priority can be set with ``priority`` option: - -.. code-block:: none - - set high-availability vrrp group Foo priority 200 - -The priority must be an integer number from 1 to 255. Higher priority value increases router's precedence in the master elections. - -Sync groups ------------ - -A sync group allows VRRP groups to transition together. - -.. code-block:: none - - edit high-availability vrrp - set sync-group MAIN member VLAN9 - set sync-group MAIN member VLAN20 - -In the following example, when VLAN9 transitions, VLAN20 will also transition: - -.. code-block:: none - - vrrp { - group VLAN9 { - interface eth0.9 - virtual-address 10.9.1.1/24 - priority 200 - vrid 9 - } - group VLAN20 { - interface eth0.20 - priority 200 - virtual-address 10.20.20.1/24 - vrid 20 - } - sync-group MAIN { - member VLAN20 - member VLAN9 - } - } - - -.. warning:: All items in a sync group should be similarly configured. If one VRRP group is set to a different premption delay or priority, it would result in an endless transition loop. - - -Preemption ----------- - -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indefinitely. - -By default VRRP uses preemption. You can disable it with the "no-preempt" option: - -.. code-block:: none - - set high-availability vrrp group Foo no-preempt - -You can also configure the time interval for preemption with the "preempt-delay" option. For example, to set the higher priority router to take over in 180 seconds, use: - -.. code-block:: none - - set high-availability vrrp group Foo preempt-delay 180 - -Unicast VRRP ------------- - -By default VRRP uses multicast packets. If your network does not support multicast for whatever reason, you can make VRRP use unicast communication instead. - -.. code-block:: none - - set high-availability vrrp group Foo peer-address 192.0.2.10 - set high-availability vrrp group Foo hello-source-address 192.0.2.15 - -Scripting ---------- - -VRRP functionality can be extended with scripts. VyOS supports two kinds of scripts: health check scripts and transition scripts. Health check scripts execute custom checks in addition to the master router reachability. -Transition scripts are executed when VRRP state changes from master to backup or fault and vice versa and can be used to enable or disable certain services, for example. - -Health check scripts -^^^^^^^^^^^^^^^^^^^^ - -This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: - -.. code-block:: none - - set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh - set high-availability vrrp group Foo health-check interval 60 - set high-availability vrrp group Foo health-check failure-count 3 - -Transition scripts -^^^^^^^^^^^^^^^^^^ - -Transition scripts can help you implement various fixups, such as starting and stopping services, or even modifying the VyOS config on VRRP transition. -This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: - -.. code-block:: none - - set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" - set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" - set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/load-balancing.rst b/docs/load-balancing.rst deleted file mode 100644 index 6b0bede9..00000000 --- a/docs/load-balancing.rst +++ /dev/null @@ -1,263 +0,0 @@ -.. _load-balancing: - -WAN load balancing -================== - -Outbound traffic can be balanced between two or more outbound interfaces. -If a path fails, traffic is balanced across the remaining healthy paths, a recovered path is automatically added back to the routing table and used by the load balancer. -The load balancer automatically adds routes for each path to the routing table and balances traffic across the configured interfaces, determined by interface health and weight. - - -In a minimal, configuration the following must be provided: - - * a interface with a nexthop - * one rule with a LAN (inbound-interface) and the WAN (interface). - -Let's assume we have two DHCP WAN interfaces and one LAN (eth2): - -.. code-block:: none - - set load-balancing wan interface-health eth0 nexthop 'dhcp' - set load-balancing wan interface-health eth1 nexthop 'dhcp' - set load-balancing wan rule 1 inbound-interface 'eth2' - set load-balancing wan rule 1 interface eth0 - set load-balancing wan rule 1 interface eth1 - -Balancing Rules ---------------- - -Interfaces, their weight and the type of traffic to be balanced are defined in numbered balancing rule sets. -The rule sets are executed in numerical order against outgoing packets. In case of a match the packet is sent through an interface specified in the matching rule. -If a packet doesn't match any rule it is sent by using the system routing table. Rule numbers can't be changed. - -Create a load balancing rule, rule can be a number between 1 and 9999: - -.. code-block:: none - - vyos@vyos# set load-balancing wan rule 1 - Possible completions: - description Description for this rule - > destination Destination - exclude Exclude packets matching this rule from wan load balance - failover Enable failover for packets matching this rule from wan load balance - inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] - +> interface Interface name [REQUIRED] - > limit Enable packet limit for this rule - per-packet-balancing Option to match traffic per-packet instead of the default, per-flow - protocol Protocol to match - > source Source information - -Interface weight -**************** - -Let's expand the example from above and add a weight to the interfaces. The bandwidth from eth0 is larger than eth1. -Per default outbound traffic is distributed randomly across available interfaces. Weights can be assigned to interfaces to influence the balancing. - -.. code-block:: none - - set load-balancing wan rule 1 interface eth0 weight 2 - set load-balancing wan rule 1 interface eth1 weight 1 - -66% traffic is routed to eth0 and eth1 get 33% of traffic. - -Rate limit -********** - -A packet rate limit can be set for a rule to apply the rule to traffic above or below a specified threshold. -To configure the rate limiting use: - -.. code-block:: none - - set load-balancing wan rule limit - -* ``burst``: Number of packets allowed to overshoot the limit within ``period``. Default 5. -* ``period``: Time window for rate calculation. Possible values: ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). Default is ``second``. -* ``rate``: Number of packets. Default 5. -* ``threshold``: ``below`` or ``above`` the specified rate limit. - -Flow and packet-based balancing -******************************* - -Outgoing traffic is balanced in a flow-based manner. -A connection tracking table is used to track flows by their source address, destination address and port. -Each flow is assigned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. -This has the advantage that packets always arrive in order if links with different speeds are in use. - -Packet-based balancing can lead to a better balance across interfaces when out of order packets are no issue. Per-packet-based balancing can be set for a balancing rule with: - -.. code-block:: none - - set load-balancing wan rule per-packet-balancing - -Exclude traffic -*************** - -To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: - -.. code-block:: none - - set load-balancing wan rule exclude - - -Health checks -------------- - -The health of interfaces and paths assigned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. -If an interface fails the health check it is removed from the load balancer's pool of interfaces. To enable health checking for an interface: - -.. code-block:: none - - vyos@vyos# set load-balancing wan interface-health - Possible completions: - failure-count Failure count - nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] - success-count Success count - +> test Rule number - -Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` - -.. code-block:: none - - set load-balancing wan interface-health nexthop - -Set the number of health check failures before an interface is marked as unavailable, range for number is 1 to 10, default 1. -Or set the number of successful health checks before an interface is added back to the interface pool, range for number is 1 to 10, default 1. - -.. code-block:: none - - set load-balancing wan interface-health failure-count - set load-balancing wan interface-health success-count - -Each health check is configured in its own test, tests are numbered and processed in numeric order. -For multi target health checking multiple tests can be defined: - -.. code-block:: none - - vyos@vyos# set load-balancing wan interface-health eth1 test 0 - Possible completions: - resp-time Ping response time (seconds) - target Health target address - test-script Path to user defined script - ttl-limit Ttl limit (hop count) - type WLB test type - -* ``resp-time``: the maximum response time for ping in seconds. Range 1...30, default 5 -* ``target``: the target to be sent ICMP packets to, address can be an IPv4 address or hostname -* ``test-script``: A user defined script must return 0 to be considered successful and non-zero to fail. Scripts are located in /config/scripts, for different locations the full path needs to be provided -* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be specified. The limit must be shorter than the path length, an ICMP time expired message is needed to be returned for a successful test. default 1 -* ``type``: Specify the type of test. type can be ping, ttl or a user defined script - -Source NAT rules ----------------- - -Per default, interfaces used in a load balancing pool replace the source IP of each outgoing packet with its own address to ensure that replies arrive on the same interface. -This works through automatically generated source NAT (SNAT) rules, these rules are only applied to balanced traffic. In cases where this behaviour is not desired, the automatic generation of SNAT rules can be disabled: - -.. code-block:: none - - set load-balancing wan disable-source-nat - -Sticky Connections ------------------- -Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. - -.. image:: /_static/images/sticky-connections.jpg - :width: 80% - :align: center - - -Upon reception of an incoming packet, when a response is sent, it might be desired to ensure that it leaves from the same interface as the inbound one. -This can be achieved by enabling sticky connections in the load balancing: - -.. code-block:: none - - set load-balancing wan sticky-connections inbound - -Failover --------- - -In failover mode, one interface is set to be the primary interface and other interfaces are secondary or spare. -Instead of balancing traffic across all healthy interfaces, only the primary interface is used and in case of failure, a secondary interface selected from the pool of available interfaces takes over. -The primary interface is selected based on its weight and health, others become secondary interfaces. -Secondary interfaces to take over a failed primary interface are chosen from the load balancer's interface pool, depending on their weight and health. -Interface roles can also be selected based on rule order by including interfaces in balancing rules and ordering those rules accordingly. To put the load balancer in failover mode, create a failover rule: - -.. code-block:: none - - set load-balancing wan rule failover - -Because existing sessions do not automatically fail over to a new path, the session table can be flushed on each connection state change: - -.. code-block:: none - - set load-balancing wan flush-connections - -.. warning:: - - Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. - -Script execution ----------------- - -A script can be run when an interface state change occurs. Scripts are run from /config/scripts, for a different location specify the full path: - -.. code-block:: none - - set load-balancing wan hook script-name - -Two environment variables are available: - -* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored -* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state - -.. warning:: - - Blocking call with no timeout. System will become unresponsive if script does not return! - -Handling and monitoring ------------------------ - - -Show WAN load balancer information including test types and targets. -A character at the start of each line depicts the state of the test - -* ``+`` successful -* ``-`` failed -* a blank indicates that no test has been carried out - -.. code-block:: none - - vyos@vyos:~$ show wan-load-balance - Interface: eth0 - Status: failed - Last Status Change: Tue Jun 11 20:12:19 2019 - -Test: ping Target: - Last Interface Success: 55s - Last Interface Failure: 0s - # Interface Failure(s): 5 - - Interface: eth1 - Status: active - Last Status Change: Tue Jun 11 20:06:42 2019 - +Test: ping Target: - Last Interface Success: 0s - Last Interface Failure: 6m26s - # Interface Failure(s): 0 - -Show connection data of load balanced traffic: - -.. code-block:: none - - vyos@vyos:~$ show wan-load-balance connection - conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. - Type State Src Dst Packets Bytes - tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 - udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 - udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 - -Restart -******* - -.. code-block:: none - - restart wan-load-balance diff --git a/docs/qos.rst b/docs/qos.rst deleted file mode 100644 index 6826b83c..00000000 --- a/docs/qos.rst +++ /dev/null @@ -1,1197 +0,0 @@ -.. _qos: - -*** -QoS -*** - -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. - -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. - - -How to make it work -=================== - -In order to have VyOS Traffic Control working you need to follow 2 -steps: - - 1. **Create a traffic policy**. - - 2. **Apply the traffic policy to an interface ingress or egress**. - - -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. - - -Units -===== - -When configuring your traffic policy, you will have to set data rate -values, watch out the units you are managing, it is easy to get confused -with the different prefixes and suffixes you can use. VyOS will always -show you the different units you can use. - -Prefixes --------- - -They can be **decimal** prefixes. - - .. code-block:: none - - kbit (10^3) kilobit per second - mbit (10^6) megabit per second - gbit (10^9) gigabit per second - tbit (10^12) terabit per second - - kbps (8*10^3) kilobyte per second - mbps (8*10^6) megabyte per second - gbps (8*10^9) gigabyte per second - tbps (8*10^12) terabyte per second - -Or **binary** prefixes. - - .. code-block:: none - - kibit (2^10 = 1024) kibibit per second - mibit (2^20 = 1024^2) mebibit per second - gibit (2^30 = 1024^3) gibibit per second - tbit (2^40 = 1024^4) tebibit per second - - kibps (1024*8) kibibyte (KiB) per second - mibps (1024^2*8) mebibyte (MiB) per second - gibps (1024^3*8) gibibyte (GiB) per second - tibps (1024^4*8) tebibyte (TiB) per second - - -Suffixes --------- - -A *bit* is written as **bit**, - - .. code-block:: none - - kbit (kilobits per second) - mbit (megabits per second) - gbit (gigabits per second) - tbit (terabits per second) - -while a *byte* is written as a single **b**. - - .. code-block:: none - - kbps (kilobytes per second) - mbps (megabytes per second) - gbps (gigabytes per second) - - - - -.. _classes: - -Classes -======= - -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. - -The ultimate goal of classifying traffic is to give each class a -different treatment. - - -Matching traffic ----------------- - -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. - -In VyOS, a class is identified by a number you can choose when -configuring it. - - -.. 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-block:: none - - set traffic-policy class match - - -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. - -A class can have multiple match filters: - -.. code-block:: none - - set traffic-policy shaper MY-SHAPER class 30 match HTTP - set traffic-policy shaper MY-SHAPER class 30 match HTTPs - -A match filter can contain multiple criteria and will match traffic if -all those criteria are true. - -For example: - -.. code-block:: none - - 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 - -This will match TCP traffic with source port 80. - -There are many parameters you will be able to use in order to match the -traffic you want for a class: - - - **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** - -When configuring your filter, you can use the ``Tab`` key to see the many -different parameters you can configure. - - -.. code-block:: none - - 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 - - - -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`_. - -You can also write a description for a filter: - -.. code-block:: none - - set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" - - - -.. note:: An IPv4 TCP filter will only match packets with an IPv4 header length of - 20 bytes (which is the majority of IPv4 packets anyway). - - -.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see - https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers - - -Default -------- - -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. - - -Class treatment ---------------- - -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. - -.. code-block:: none - - vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 - Possible completions: - bandwidth Bandwidth used for this class - burst Burst size for this class (default: 15kb) - ceiling Bandwidth limit for this class - codel-quantum - fq-codel - Number of bytes used as 'deficit' (default 1514) - description Description for this traffic class - flows fq-codel - Number of flows (default 1024) - interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) - +> match Class matching rule name - priority Priority for usage of excess bandwidth - queue-limit Maximum queue size (packets) - queue-type Queue type for this class - set-dscp Change the Differentiated Services (DiffServ) field in the IP header - target fq-codel - Acceptable minimum queue delay (milliseconds) - - -For instance, with :code:`set traffic-policy shaper MY-SHAPER class 30 set-dscp EF` -you would be modifying the DSCP field value of packets in that class to -Expedite Forwarding. - - - DSCP values as per :rfc:`2474` and :rfc:`4595`: - - +---------+------------+--------+------------------------------+ - | 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 | - +---------+------------+--------+------------------------------+ - - - - -.. _embed: - -Embedding one policy into another one -------------------------------------- - -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. - -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 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. - -You can configure a policy into a class through the ``queue-type`` -setting. - -.. code-block:: none - - set traffic-policy shaper FQ-SHAPER bandwidth 4gbit - set traffic-policy shaper FQ-SHAPER default bandwidth 100% - set traffic-policy shaper FQ-SHAPER default queue-type fq-codel - -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. - -.. note:: Some policies already include other embedded policies inside. - That is the case of Shaper_: each of its classes use fair-queue - unless you change it. - -.. _creating_a_traffic_policy: - - -Creating a traffic policy -========================= - -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). - -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. - -.. hint:: **If you are looking for a policy for your outbound traffic** - but you don't know which one you need and you don't want to go - through every possible policy shown here, **our bet is that highly - likely you are looking for a** Shaper_ **policy and you want to** - :ref:`set its queues ` **as FQ-CoDel**. - -Drop Tail ---------- - -| **Queueing discipline:** PFIFO (Packet First In First Out). -| **Applies to:** Outbound traffic. - -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. - -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. - -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. - -This is the policy that requieres the lowest resources for the same -amount of traffic. But **very likely you do not need it as you cannot -get much from it. Sometimes it is used just to enable logging.** - -.. cfgcmd:: set traffic-policy drop-tail queue-limit - - 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). - - -Fair Queue ----------- - -| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). -| **Applies to:** Outbound traffic. - -Fair Queue is a work-conserving scheduler which schedules the -transmission of packets based on flows, that is, it balances traffic -distributing it through different sub-queues in order to ensure -fairness so that each flow is able to send data in turn, preventing any -single one from drowning out the rest. - - -.. cfgcmd:: set traffic-policy fair-queue - - 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. - -In order to separate traffic, Fair Queue uses a classifier based on -source address, destination address and source port. The algorithm -enqueues packets to hash buckets based on those tree parameters. -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. - -One of the uses of Fair Queue might be the mitigation of Denial of -Service attacks. - -.. cfgcmd:: set traffic-policy fair-queue hash-interval ` - - 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). - -When dequeuing, each hash-bucket with data is queried in a round robin -fashion. You can configure the length of the queue. - -.. cfgcmd:: set traffic-policy fair-queue queue-limit - - 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. - -.. 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. - - - -.. _FQ-CoDel: - -FQ-CoDel --------- - -| **Queueing discipline** Fair/Flow Queue CoDel. -| **Applies to:** Outbound Traffic. - -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. - -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. - -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. - -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. - - -.. 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. - - -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. - -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. - -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. - -On low rates (below 40Mbit) you may want to tune `quantum` down to -something like 300 bytes. - -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. - - -.. cfgcmd:: set traffic-policy fq-codel codel-quantum - - 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. - -.. cfgcmd:: set traffic-policy fq-codel flows - - 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. - -.. cfgcmd:: set traffic-policy fq-codel interval - - 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). - -.. cfgcmd:: set traffic-policy fq-codel queue-limit ` - - 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). - -.. cfgcmd:: set traffic-policy fq-codel target ` - - 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). - - -Example -^^^^^^^ - -A simple example of an FQ-CoDel policy working inside a Shaper one. - - -.. code-block:: none - - set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit - set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% - set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel - - - -Limiter -------- - -| **Queueing discipline:** Ingress policer. -| **Applies to:** Inbound traffic. - -Limiter is one of those policies that uses classes_ (Ingress qdisc is -actually a classless policy but filters do work in it). - -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. - -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. - - -.. note:: In the case you want to apply some kind of **shaping** to your - **inbound** traffic, check the ingress-shaping_ section. - - -.. cfgcmd:: set traffic-policy limiter class match description - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090), a class matching rule name and its - description. - - -Once the matching rules are set for a class, you can start configuring -how you want matching traffic to behave. - - -.. cfgcmd:: set traffic-policy limiter class bandwidth - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090) and the maximum allowed bandwidth for - this class. - - -.. cfgcmd:: set traffic-policy limiter class burst - - 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). - - -.. cfgcmd:: set traffic-policy limiter default bandwidth - - Use this command to configure an Ingress Policer, defining its name - and the maximum allowed bandwidth for its default policy. - - -.. cfgcmd:: set traffic-policy limiter default burst - - Use this command to configure an Ingress Policer, defining its name - and the burst size in bytes (default: 15) for its default policy. - - -.. cfgcmd:: set traffic-policy limiter class 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). - - - -Network Emulator ----------------- - -| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). -| **Applies to:** Outbound traffic. - -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. - -This could be helpful if you want to test how an application behaves -under certain network conditions. - - -.. cfgcmd:: set traffic-policy network-emulator bandwidth - - Use this command to configure the maximum rate at which traffic will - be shaped in a Network Emulator policy. Define the name of the policy - and the rate. - -.. cfgcmd:: set traffic-policy network-emulator burst - - 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 be configured through the - Token Bucket Filter qdisc). Default:15kb. It will only take effect if - you have configured its bandwidth too. - -.. cfgcmd:: set traffic-policy network-emulator network-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. The latency will be added through the - Token Bucket Filter qdisc. It will only take effect if you have - configured its bandwidth too. You can use secs, ms and us. Default: - 50ms. - -.. cfgcmd:: set traffic-policy network-emulator packet-corruption - - 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. - -.. cfgcmd:: set traffic-policy network-emulator packet-loss ` - - 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. - -.. cfgcmd:: set traffic-policy network-emulator packet-reordering ` - - Use this command to emulate packet-reordering conditions in a Network - Emulator policy. Set the policy name and the percentage of reordered - packets your traffic will suffer. - -.. cfgcmd:: set traffic-policy network-emulator queue-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. - - - -Priority Queue --------------- - -| **Queueing discipline:** PRIO. -| **Applies to:** Outbound traffic. - - -The Priority Queue is a classful scheduling policy. It does not delay -packets (Priority Queue is not a shaping policy), it simply dequeues -packets according to their priority. - -.. 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. - -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. - - -.. 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. - - -As with other policies, you can define different type of matching rules -for your classes: - -.. code-block:: none - - 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 - - -As with other policies, you can embed_ other policies into the classes -(and default) of your Priority Queue policy through the ``queue-type`` -setting: - -.. code-block:: none - - 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) - - -.. cfgcmd:: set traffic-policy priority-queue class queue-limit ` - - 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. - - - -.. _Random-Detect: - -Random-Detect -------------- - - -| **Queueing discipline:** Generalized Random Early Drop. -| **Applies to:** Outbound traffic. - -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. - -In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random -Early Detect policy that provides different virtual queues based on the -IP Precedence value so that some virtual queues can drop more packets -than others. - -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. - -IP precedence 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 | - +------------+----------------------+ - - -Random-Detect could be useful for heavy traffic. One use of this -algorithm might be to prevent a backbone overload. But only for TCP -(because dropped packets could be retransmitted), not for UDP. - - -.. cfgcmd:: set traffic-policy random-detect bandwidth - - Use this command to configure a Random-Detect policy, set its name - and set the available bandwidth for this policy. It is used for - calculating the average queue size after some idle time. It should be - set to the bandwidth of your interface. Random Detect is not a - shaping policy, this command will not shape. - -.. cfgcmd:: set traffic-policy random-detect precedence average-packet - - 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). - -.. note:: When configuring a Random-Detect policy: **the higher the - precedence number, the higher the priority**. - -.. cfgcmd:: set traffic-policy random-detect precedence mark-probability - - 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). - - -.. cfgcmd:: set traffic-policy random-detect precedence maximum-threshold - - 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. - -.. cfgcmd:: set traffic-policy random-detect precedence minimum-threshold - - 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. - - -The default values for the minimum-threshold depend on IP precedence: - - +------------+-----------------------+ - | Precedence | default min-threshold | - +============+=======================+ - | 7 | 16 | - +------------+-----------------------+ - | 6 | 15 | - +------------+-----------------------+ - | 5 | 14 | - +------------+-----------------------+ - | 4 | 13 | - +------------+-----------------------+ - | 3 | 12 | - +------------+-----------------------+ - | 2 | 11 | - +------------+-----------------------+ - | 1 | 10 | - +------------+-----------------------+ - | 0 | 9 | - +------------+-----------------------+ - - -.. cfgcmd:: set traffic-policy random-detect precedence queue-limit - - 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. - - -If the average queue size is lower than the **min-threshold**, an -arriving packet will be placed in the queue. - -In the case the average queue size is between **min-threshold** and -**max-threshold**, then an arriving packet would be either dropped or -placed in the queue, it will depend on the defined **mark-probability**. - -If the current queue size is larger than **queue-limit**, -then packets will be dropped. The average queue size depends on its -former average size and its current one. - -If **max-threshold** is set but **min-threshold is not, then -**min-threshold** is scaled to 50% of **max-threshold**. - -In principle, values must be -:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. - - - - -Rate Control ------------- - -| **Queueing discipline:** Tocken Bucket Filter. -| **Applies to:** Outbound traffic. - -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. - -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. - -.. cfgcmd:: set traffic-policy rate-control bandwidth - - Use this command to configure a Rate-Control policy, set its name - and the rate limit you want to have. - -.. cfgcmd:: set traffic-policy rate-control burst - - 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. - - -As a reference: for 10mbit/s on Intel, you might need at least 10kbyte -buffer if you want to reach your configured rate. - -A very small buffer will soon start dropping packets. - -.. cfgcmd:: set traffic-policy rate-control latency - - 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). - - -Rate-Control is a CPU-friendly policy. You might consider using it when -you just simply want to slow traffic down. - -.. _DRR: - -Round Robin ------------ - -| **Queueing discipline:** Deficit Round Robin. -| **Applies to:** Outbound traffic. - -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. - -At every round, the deficit counter adds the quantum so that even large -packets will have their opportunity to be dequeued. - - -.. cfgcmd:: set traffic-policy round-robin class - quantum - - 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. - -.. cfgcmd:: set traffic-policy round-robin class - queue-limit - - Use this command to configure a Round-Robin policy, set its name, set - a class ID, and the queue size in packets. - -As with other policies, Round-Robin can embed_ another policy into a -class through the ``queue-type`` setting. - -.. code-block:: none - - 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 - - - - -.. _Shaper: - -Shaper ------- - -| **Queueing discipline:** Hierarchical Token Bucket. -| **Applies to:** Outbound traffic. - - -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. - -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. - -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. - - -.. cfgcmd:: set traffic-policy shaper bandwidth - - Use this command to configure a Shaper policy, set its name - and the maximum bandwidth for all combined traffic. - - -.. cfgcmd:: set traffic-policy shaper class bandwidth - - 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. - -.. cfgcmd:: set traffic-policy shaper class burst - - 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 ceiling speed (default: 15Kb). - -.. cfgcmd:: set traffic-policy shaper class ceiling - - 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. - -.. cfgcmd:: set traffic-policy shaper class priority <0-7> - - 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. - - -As with other policies, Shaper can embed_ other policies into its -classes through the ``queue-type`` setting and then configure their -parameters. - - -.. code-block:: none - - 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) - - -.. code-block:: none - - 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) - - - -.. note:: If you configure a class for **VoIP traffic**, don't give it any - *ceiling*, otherwise new VoIP calls could start when the link is - available and get suddenly dropped when other classes start using - their assigned *bandwidth* share. - - -Example -^^^^^^^ - -A simple example of Shaper using priorities. - - -.. code-block:: none - - set traffic-policy shaper MY-HTB bandwidth '50mbit' - set traffic-policy shaper MY-HTB class 10 bandwidth '20%' - set traffic-policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' - set traffic-policy shaper MY-HTB class 10 queue-type 'fq-codel' - 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 PORT666 ip destination port '666' - 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' - - -Applying a traffic policy -========================= - -Once a traffic-policy is created, you can apply it to an interface: - -.. code-block:: none - - set interfaces etherhet eth0 traffic-policy out WAN-OUT - -You can only apply one policy per interface and direction, but you could -reuse a policy on different interfaces and directions: - -.. code-block:: none - - set interfaces ethernet eth0 traffic-policy in WAN-IN - set interfaces etherhet eth0 traffic-policy out WAN-OUT - set interfaces etherhet eth1 traffic-policy in LAN-IN - set interfaces etherhet eth1 traffic-policy out LAN-OUT - set interfaces ethernet eth2 traffic-policy in LAN-IN - set interfaces ethernet eth2 traffic-policy out LAN-OUT - set interfaces etherhet eth3 traffic-policy in TWO-WAY-POLICY - set interfaces etherhet eth3 traffic-policy out TWO-WAY-POLICY - set interfaces etherhet eth4 traffic-policy in TWO-WAY-POLICY - set interfaces etherhet eth4 traffic-policy out TWO-WAY-POLICY - -Getting queueing information ----------------------------- - -.. opcmd:: show queueing - - Use this command to see the queueing information for an interface. - You will be able to see a packet counter (Sent, Dropped, Overlimit - and Backlog) per policy and class configured. - - - -.. _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. You cannot apply a shaping -policy directly to the ingress traffic of any interface because shaping -only works for outbound traffic. - -This workaround lets you apply a shaping policy to the ingress traffic -by first redirecting it to an in-between virtual interface -(`Intermediate Functional Block`_). There, in that virtual interface, -you will be able to apply any of the policies that work for outbound -traffic, for instance, a shaping one. - -That is how it is possible to do the so-called "ingress shaping". - - -.. code-block:: none - - 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 - -.. warning:: - - Do not configure IFB as the first step. First create everything else - of your traffic-policy, and then you can configure IFB. - Otherwise you might get the ``RTNETLINK answer: File exists`` error, - which can be solved with ``sudo ip link delete ifb0``. - - -.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches -.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) -.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket -.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve -.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb -- cgit v1.2.3 From e7f01e6efc8578603592ff86c031d46f1f1f9d82 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:32:45 +0100 Subject: arrange: nat, PBR, policy --- docs/configuration/nat/index.rst | 739 ++++++++++++++++++++++++++++++++++++ docs/configuration/nat/nptv6.rst | 69 ++++ docs/configuration/policy/index.rst | 205 ++++++++++ docs/nat.rst | 733 ----------------------------------- docs/nptv6.rst | 69 ---- docs/routing/pbr.rst | 137 ------- docs/routing/policy.rst | 65 ---- 7 files changed, 1013 insertions(+), 1004 deletions(-) create mode 100644 docs/configuration/nat/index.rst create mode 100644 docs/configuration/nat/nptv6.rst create mode 100644 docs/configuration/policy/index.rst delete mode 100644 docs/nat.rst delete mode 100644 docs/nptv6.rst delete mode 100644 docs/routing/pbr.rst delete mode 100644 docs/routing/policy.rst (limited to 'docs/configuration') diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst new file mode 100644 index 00000000..85bd41d5 --- /dev/null +++ b/docs/configuration/nat/index.rst @@ -0,0 +1,739 @@ +.. _nat: + +### +NAT +### + +.. toctree:: + :maxdepth: 1 + :includehidden: + + nptv6 + +:abbr:`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the :abbr:`IANA (Internet Assigned Numbers Authority)` for +private addressing (see :rfc:`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +* 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + + +If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses +:rfc:`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an :rfc:`1918` address space. + +This prompted some ISPs to develop a policy within the :abbr:`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per :rfc:`2860`). + +IETF published :rfc:`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the :abbr:`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat: + +SNAT +^^^^ + +:abbr:`SNAT (Source Network Address Translation)` is the most common +form of :abbr:`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as :abbr:`NAT (Network Address Translation)` is actually the process +of :abbr:`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +- the source address is translated and thus kept private. + +.. _destination-nat: + +DNAT +^^^^ + +:abbr:`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +:ref:`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +.. _bidirectional-nat: + +Bidirectional NAT +^^^^^^^^^^^^^^^^^ + +This is a common scenario where both :ref:`source-nat` and +:ref:`destination-nat` are configured at the same time. It's commonly +used then internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +NAT, Routing, Firewall Interaction +---------------------------------- + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +NAT Ruleset +----------- + +:abbr:`NAT (Network Address Translation)` is configured entirely on a +series of so called `rules`. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the :cfgcmd:`rename` and :cfgcmd:`copy` commands. + +.. note:: Changes to the NAT system only affect newly established + connections. Already established connections are not affected. + +.. hint:: When designing your NAT ruleset leave some space between + consecutive rules for later extension. Your ruleset could start with + numbers 10, 20, 30. You thus can later extend the ruleset and place + new rules between existing ones. + +Rules will be created for both :ref:`source-nat` and +:ref:`destination-nat`. + +For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and +:ref:`destination-nat` needs to be created. + +.. _traffic-filters: + +Traffic Filters +--------------- + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +* **outbound-interface** - applicable only to :ref:`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. + + Example: + + .. code-block:: none + + set nat source rule 20 outbound-interface eth0 + +* **inbound-interface** - applicable only to :ref:`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. + + Example: + + .. code-block:: none + + set nat destination rule 20 inbound-interface eth1 + +* **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. By default this + applies to `all` protocols. + + Example: + + * Set SNAT rule 20 to only NAT TCP and UDP packets + * Set DNAT rule 20 to only NAT UDP packets + + .. code-block:: none + + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + +* **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + * Set SNAT rule 30 to only NAT packets arriving from the 192.0.3.0/24 + network with a source port of 80 and 443 + + .. code-block:: none + + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 192.0.3.0/24 + set nat source rule 30 source port 80,443 + + +* **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + .. note:: If no destination is specified the rule will match on any + destination address and port. + + Example: + + * Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + .. code-block:: none + + set nat source rule 40 destination address 192.0.2.1 + + +Address Conversion +------------------ + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +Source Address +^^^^^^^^^^^^^^ + +For :ref:`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +.. note:: The translation address must be set to one of the available + addresses on the configured `outbound-interface` or it must be set to + `masquerade` which will use the primary IP address of the + `outbound-interface` as its translation address. + +.. note:: When using NAT for a large number of host systems it + recommended that a minimum of 1 IP address is used to NAT every 256 + private host systems. This is due to the limit of 65,000 port numbers + available for unique translations and a reserving an average of + 200-300 sessions per host system. + +Example: + +* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +* Use address `masquerade` (the interfaces primary address) on rule 30 +* For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + + +.. code-block:: none + + set nat source rule 20 translation address 100.64.0.1 + set nat source rule 30 translation address 'masquerade' + set nat source rule 40 translation address 100.64.0.10-100.64.0.20 + + +Destination Address +^^^^^^^^^^^^^^^^^^^ + +For :ref:`destination-nat` rules the packets destination address will be +replaced by the specified address in the `translation address` command. + +Example: + +* DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +.. code-block:: none + + set nat destination rule 10 translation address 192.0.2.10 + + +Configuration Examples +====================== + +To setup SNAT, we need to know: + +* The internal IP addresses we want to translate +* The outgoing interface to perform the translation on +* The external IP address to translate to + +In the example used for the Quick Start configuration above, we +demonstrate the following configuration: + +.. code-block:: none + + set nat source rule 100 outbound-interface 'eth0' + set nat source rule 100 source address '192.168.0.0/24' + set nat source rule 100 translation address 'masquerade' + +Which generates the following configuration: + +.. code-block:: none + + rule 100 { + outbound-interface eth0 + source { + address 192.168.0.0/24 + } + translation { + address masquerade + } + } + +In this example, we use **masquerade** as the translation address +instead of an IP address. The **masquerade** target is effectively an +alias to say "use whatever IP address is on the outgoing interface", +rather than a statically configured IP address. This is useful if you +use DHCP for your outgoing interface and do not know what the external +address will be. + +When using NAT for a large number of host systems it recommended that a +minimum of 1 IP address is used to NAT every 256 host systems. This is +due to the limit of 65,000 port numbers available for unique +translations and a reserving an average of 200-300 sessions per host +system. + +Example: For an ~8,000 host network a source NAT pool of 32 IP addresses +is recommended. + +A pool of addresses can be defined by using a hyphen between two IP +addresses: + +.. code-block:: none + + set nat source rule 100 translation address '203.0.113.32-203.0.113.63' + +.. _avoidng_leaky_nat: + +Avoiding "leaky" NAT +-------------------- + +Linux netfilter will not NAT traffic marked as INVALID. This often +confuses people into thinking that Linux (or specifically VyOS) has a +broken NAT implementation because non-NATed traffic is seen leaving an +external interface. This is actually working as intended, and a packet +capture of the "leaky" traffic should reveal that the traffic is either +an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems +after Linux netfilter considers the connection closed. The most common +is the additional TCP RST some host implementations send after +terminating a connection (which is implementation-specific). + +In other words, connection tracking has already observed the connection +be closed and has transition the flow to INVALID to prevent attacks from +attempting to reuse the connection. + +You can avoid the "leaky" behavior by using a firewall policy that drops +"invalid" state packets. + +Having control over the matching of INVALID state traffic, e.g. the +ability to selectively log, is an important troubleshooting tool for +observing broken protocol behavior. For this reason, VyOS does not +globally drop invalid state traffic, instead allowing the operator to +make the determination on how the traffic is handled. + +.. _hairpin_nat_reflection: + +Hairpin NAT/NAT Reflection +-------------------------- + +A typical problem with using NAT and hosting public servers is the +ability for internal systems to reach an internal server using it's +external IP address. The solution to this is usually the use of +split-DNS to correctly point host systems to the internal address when +requests are made internally. Because many smaller networks lack DNS +infrastructure, a work-around is commonly deployed to facilitate the +traffic by NATing the request from internal hosts to the source address +of the internal interface on the firewall. + +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: + +* Redirect Microsoft RDP traffic from the outside (WAN, external) world + via :ref:`destination-nat` in rule 100 to the internal, private host + 192.0.2.40. + +* Redirect Microsoft RDP traffic from the internal (LAN, private) + network via :ref:`destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a :ref:`source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface `eth0.10`. + +.. code-block:: none + + set nat destination rule 100 description 'Regular destination NAT from external' + set nat destination rule 100 destination port '3389' + set nat destination rule 100 inbound-interface 'pppoe0' + set nat destination rule 100 protocol 'tcp' + set nat destination rule 100 translation address '192.0.2.40' + + set nat destination rule 110 description 'NAT Reflection: INSIDE' + set nat destination rule 110 destination port '3389' + set nat destination rule 110 inbound-interface 'eth0.10' + set nat destination rule 110 protocol 'tcp' + set nat destination rule 110 translation address '192.0.2.40' + + set nat source rule 110 description 'NAT Reflection: INSIDE' + set nat source rule 110 destination address '192.0.2.0/24' + set nat source rule 110 outbound-interface 'eth0.10' + set nat source rule 110 protocol 'tcp' + set nat source rule 110 source address '192.0.2.0/24' + set nat source rule 110 translation address 'masquerade' + +Which results in a configuration of: + +.. code-block:: none + + vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface pppoe0 + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface eth0.10 + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface eth0.10 + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } + + +Destination NAT +--------------- + +DNAT is typically referred to as a **Port Forward**. When using VyOS as +a NAT router and firewall, a common configuration task is to redirect +incoming traffic to a system behind the firewall. + +In this example, we will be using the example Quick Start configuration +above as a starting point. + +To setup a destination NAT rule we need to gather: + +* The interface traffic will be coming in on; +* The protocol and port we wish to forward; +* The IP address of the internal system we wish to forward traffic to. + +In our example, we will be forwarding web server traffic to an internal +web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol +on port 80. For other common port numbers, see: +https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers + +Our configuration commands would be: + +.. code-block:: none + + set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' + set nat destination rule 10 destination port '80' + set nat destination rule 10 inbound-interface 'eth0' + set nat destination rule 10 protocol 'tcp' + set nat destination rule 10 translation address '192.168.0.100' + +Which would generate the following NAT destination configuration: + +.. code-block:: none + + nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface eth0 + protocol tcp + translation { + address 192.168.0.100 + } + } + } + } + +.. note:: If forwarding traffic to a different port than it is arriving + on, you may also configure the translation port using + `set nat destination rule [n] translation port`. + +This establishes our Port Forward rule, but if we created a firewall +policy it will likely block the traffic. + +It is important to note that when creating firewall rules that the DNAT +translation occurs **before** traffic traverses the firewall. In other +words, the destination address has already been translated to +192.168.0.100. + +So in our firewall policy, we want to allow traffic coming in on the +outside interface, destined for TCP port 80 and the IP address of +192.168.0.100. + +.. code-block:: none + + set firewall name OUTSIDE-IN rule 20 action 'accept' + set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100' + set firewall name OUTSIDE-IN rule 20 destination port '80' + set firewall name OUTSIDE-IN rule 20 protocol 'tcp' + set firewall name OUTSIDE-IN rule 20 state new 'enable' + +This would generate the following configuration: + +.. code-block:: none + + rule 20 { + action accept + destination { + address 192.168.0.100 + port 80 + } + protocol tcp + state { + new enable + } + } + +.. note:: + + If you have configured the `INSIDE-OUT` policy, you will need to add + additional rules to permit inbound NAT traffic. + +1-to-1 NAT +---------- + +Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT +configuration, both DNAT and SNAT are used to NAT all traffic from an +external IP address to an internal IP address and vice-versa. + +Typically, a 1-to-1 NAT rule omits the destination port (all ports) and +replaces the protocol with either **all** or **ip**. + +Then a corresponding SNAT rule is created to NAT outgoing traffic for +the internal IP to a reserved external IP. This dedicates an external IP +address to an internal IP address and is useful for protocols which +don't have the notion of ports, such as GRE. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +.. code-block:: none + + set interfaces ethernet eth0 address '192.168.1.1/24' + set interfaces ethernet eth0 description 'Inside interface' + set interfaces ethernet eth1 address '192.0.2.30/24' + set interfaces ethernet eth1 description 'Outside interface' + set nat destination rule 2000 description '1-to-1 NAT example' + set nat destination rule 2000 destination address '192.0.2.30' + set nat destination rule 2000 inbound-interface 'eth1' + set nat destination rule 2000 translation address '192.168.1.10' + set nat source rule 2000 description '1-to-1 NAT example' + set nat source rule 2000 outbound-interface 'eth1' + set nat source rule 2000 source address '192.168.1.10' + set nat source rule 2000 translation address '192.0.2.30' + +Firewall rules are written as normal, using the internal IP address as +the source of outbound rules and the destination of inbound rules. + +NAT before VPN +-------------- + +Some application service providers (ASPs) operate a VPN gateway to +provide access to their internal resources, and require that a +connecting organisation translate all traffic to the service provider +network to a source address provided by the ASP. + +Example Network +^^^^^^^^^^^^^^^ + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at +the customer site. + +.. figure:: _static/images/nat_before_vpn_topology.png + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology + + +Configuration +^^^^^^^^^^^^^ + +The required configuration can be broken down into 4 major pieces: + +* A dummy interface for the provider-assigned IP; +* NAT (specifically, Source NAT); +* IPSec IKE and ESP Groups; +* IPSec VPN tunnels. + + +Dummy interface +""""""""""""""" + +The dummy interface allows us to have an equivalent of the Cisco IOS +Loopback interface - a router-internal interface we can use for IP +addresses the router must know about, but which are not actually +assigned to a real network. + +We only need a single step for this interface: + +.. code-block:: none + + set interfaces dummy dum0 address '172.29.41.89/32' + +NAT Configuration +""""""""""""""""" + +.. code-block:: none + + set nat source rule 110 description 'Internal to ASP' + set nat source rule 110 destination address '172.27.1.0/24' + set nat source rule 110 outbound-interface 'any' + set nat source rule 110 source address '192.168.43.0/24' + set nat source rule 110 translation address '172.29.41.89' + set nat source rule 120 description 'Internal to ASP' + set nat source rule 120 destination address '10.125.0.0/16' + set nat source rule 120 outbound-interface 'any' + set nat source rule 120 source address '192.168.43.0/24' + set nat source rule 120 translation address '172.29.41.89' + +IPSec IKE and ESP +""""""""""""""""" + +The ASP has documented their IPSec requirements: + +* IKE Phase: + + * aes256 Encryption + * sha256 Hashes + +* ESP Phase: + + * aes256 Encryption + * sha256 Hashes + * DH Group 14 + + +Additionally, we want to use VPNs only on our eth1 interface (the +external interface in the image above) + +.. code-block:: none + + set vpn ipsec ike-group my-ike ikev2-reauth 'no' + set vpn ipsec ike-group my-ike key-exchange 'ikev1' + set vpn ipsec ike-group my-ike lifetime '7800' + set vpn ipsec ike-group my-ike proposal 1 dh-group '14' + set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + + set vpn ipsec esp-group my-esp compression 'disable' + set vpn ipsec esp-group my-esp lifetime '3600' + set vpn ipsec esp-group my-esp mode 'tunnel' + set vpn ipsec esp-group my-esp pfs 'disable' + set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + + set vpn ipsec ipsec-interfaces interface 'eth1' + +IPSec VPN Tunnels +""""""""""""""""" + +We'll use the IKE and ESP groups created above for this VPN. Because we +need access to 2 different subnets on the far side, we will need two +different tunnels. If you changed the names of the ESP group and IKE +group in the previous step, make sure you use the correct names here +too. + +.. code-block:: none + + set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' + set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' + set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' + set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' + set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' + +Testing and Validation +"""""""""""""""""""""" + +If you've completed all the above steps you no doubt want to see if it's +all working. + +Start by checking for IPSec SAs (Security Associations) with: + +.. code-block:: none + + $ show vpn ipsec sa + + Peer ID / IP Local ID / IP + ------------ ------------- + 198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all + +That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/nptv6.rst b/docs/configuration/nat/nptv6.rst new file mode 100644 index 00000000..f4e08325 --- /dev/null +++ b/docs/configuration/nat/nptv6.rst @@ -0,0 +1,69 @@ +.. include:: _include/need_improvement.txt + +.. _nptv6: + +##### +NPTv6 +##### + +:abbr:`NPTv6 (Network Prefix Translation)` is a form of NAT for IPv6. It's +described in :rfc:`6296`. + +**Usage** + +NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the +external IPv6 prefix is dynamic, as it prevents the need for renumbering of +internal hosts when the extern prefix changes. + +Let's assume the following network configuration: + +* eth0 : LAN +* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it +* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it + +Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over +2001:db8:e2::/48? What happens when you get a new provider with a different +routed IPv6 subnet? + +The solution here is to assign to your hosts ULAs_ and to prefix-translate +their address to the right subnet when going through your router. + +* LAN Subnet : fc00:dead:beef::/48 +* WAN 1 Subnet : 2001:db8:e1::/48 +* WAN 2 Subnet : 2001:db8:e2::/48 + +* eth0 addr : fc00:dead:beef::1/48 +* eth1 addr : 2001:db8:e1::1/48 +* eth2 addr : 2001:db8:e2::1/48 + +VyOS Support +^^^^^^^^^^^^ + +NPTv6 support has been added in VyOS 1.2 (Crux) and is available through +`nat nptv6` configuration nodes. + +.. code-block:: none + + set rule 10 source prefix 'fc00:dead:beef::/48' + set rule 10 outbound-interface 'eth1' + set rule 10 translation prefix '2001:db8:e1::/48' + set rule 20 source prefix 'fc00:dead:beef::/48' + set rule 20 outbound-interface 'eth2' + set rule 20 translation prefix '2001:db8:e2::/48' + +Resulting in the following ip6tables rules: + +.. code-block:: none + + Chain VYOS_DNPT_HOOK (1 references) + pkts bytes target prot opt in out source destination + 0 0 NETMAP all eth1 any anywhere 2001:db8:e1::/48 to:fc00:dead:beef::/48 + 0 0 NETMAP all eth2 any anywhere 2001:db8:e2::/48 to:fc00:dead:beef::/48 + 0 0 RETURN all any any anywhere anywhere + Chain VYOS_SNPT_HOOK (1 references) + pkts bytes target prot opt in out source destination + 0 0 NETMAP all any eth1 fc00:dead:beef::/48 anywhere to:2001:db8:e1::/48 + 0 0 NETMAP all any eth2 fc00:dead:beef::/48 anywhere to:2001:db8:e2::/48 + 0 0 RETURN all any any anywhere anywhere + +.. _ULAs: https://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst new file mode 100644 index 00000000..4be494e5 --- /dev/null +++ b/docs/configuration/policy/index.rst @@ -0,0 +1,205 @@ +.. include:: ../_include/need_improvement.txt + +###### +Policy +###### + +Routing Policies could be used to tell the router (self or neighbors) what +routes and their attributes needs to be put into the routing table. + +There could be a wide range of routing policies. Some examples are below: + +* Set some metric to routes learned from a particular neighbor +* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors +* Prefer a specific routing protocol routes over another routing protocol running on the same router + +Example +======= + +**Policy definition:** + +.. code-block:: none + + # Create policy + set policy route-map setmet rule 2 action 'permit' + set policy route-map setmet rule 2 set as-path-prepend '2 2 2' + + # Apply policy to BGP + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ show ip bgp + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + + Total number of prefixes 1 + +**Routes learned after routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ sho ip b + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + + Total number of prefixes 1 + vyos@vos1:~$ + +You now see the longer AS path. + + +.. include:: ../_include/need_improvement.txt + +.. _routing-pbr: + +### +PBR +### + +:abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to +different routing tables. Traffic can be matched using standard 5-tuple +matching (source address, destination address, protocol, source port, +destination port). + +Transparent Proxy +================= + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +.. code-block:: none + + set policy route FILTER-WEB rule 1000 destination port 80 + set policy route FILTER-WEB rule 1000 protocol tcp + set policy route FILTER-WEB rule 1000 set table 100 + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +.. code-block:: none + + set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 + +This can be confirmed using the ``show ip route table 100`` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +.. code-block:: none + + set interfaces ethernet eth1 policy route FILTER-WEB + + +Multiple Uplinks +================ + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24) +* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24) +* ``main`` Routing table used by VyOS and other interfaces not + participating in PBR + +.. figure:: ../_static/images/pbr_example_1.png + :scale: 80 % + :alt: PBR multiple uplinks + + Policy-Based Routing with multiple ISP uplinks + (source ./draw.io/pbr_example_1.drawio) + +Add default routes for routing ``table 10`` and ``table 11`` + +.. code-block:: none + + set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1 + set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 + +Add policy route matching VLAN source addresses + +.. code-block:: none + + set policy route PBR rule 20 set table '10' + set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' + set policy route PBR rule 20 source address '192.168.188.0/24' + + set policy route PBR rule 30 set table '11' + set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' + set policy route PBR rule 30 source address '192.168.189.0/24' + +Apply routing policy to **inbound** direction of out VLAN interfaces + +.. code-block:: none + + set interfaces ethernet eth0 vif 10 policy route 'PBR' + set interfaces ethernet eth0 vif 11 policy route 'PBR' + + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +.. code-block:: none + + set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' + set policy route PBR rule 10 destination address '192.168.188.0/24' + set policy route PBR rule 10 destination address '192.168.189.0/24' + set policy route PBR rule 10 set table 'main' + +These commands allow the VLAN10 and VLAN20 hosts to communicate with +each other using the main routing table. + +Local route +=========== + +The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` for traffic, which originated from the router itself. +That solution for multiple ISP's and VyOS router will respond from the same interface that the packet was received. +Also, it used, if we want that one VPN tunnel to be through one provider, and the second through another. + +* ``192.168.1.254`` IP addreess on VyOS eth1 from ISP1 +* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2 +* ``table 10`` Routing table used for ISP1 +* ``table 11`` Routing table used for ISP2 + + +.. code-block:: none + + set policy local-route rule 101 set table '10' + set policy local-route rule 101 source '192.0.1.254' + set policy local-route rule 102 set table '11' + set policy local-route rule 102 source '192.0.2.254' + set protocols static table 10 route '0.0.0.0/0' next-hop '192.0.1.1' + set protocols static table 11 route '0.0.0.0/0' next-hop '192.0.2.2' + +Add multiple source IP in one rule with same priority + +.. code-block:: none + + set policy local-route rule 101 set table '10' + set policy local-route rule 101 source '192.0.1.254' + set policy local-route rule 101 source '192.0.1.253' + set policy local-route rule 101 source '203.0.113.0/24' + diff --git a/docs/nat.rst b/docs/nat.rst deleted file mode 100644 index 17698c26..00000000 --- a/docs/nat.rst +++ /dev/null @@ -1,733 +0,0 @@ -.. _nat: - -### -NAT -### - -:abbr:`NAT (Network Address Translation)` is a common method of -remapping one IP address space into another by modifying network address -information in the IP header of packets while they are in transit across -a traffic routing device. The technique was originally used as a -shortcut to avoid the need to readdress every host when a network was -moved. It has become a popular and essential tool in conserving global -address space in the face of IPv4 address exhaustion. One -Internet-routable IP address of a NAT gateway can be used for an entire -private network. - -IP masquerading is a technique that hides an entire IP address space, -usually consisting of private IP addresses, behind a single IP address -in another, usually public address space. The hidden addresses are -changed into a single (public) IP address as the source address of the -outgoing IP packets so they appear as originating not from the hidden -host but from the routing device itself. Because of the popularity of -this technique to conserve IPv4 address space, the term NAT has become -virtually synonymous with IP masquerading. - -As network address translation modifies the IP address information in -packets, NAT implementations may vary in their specific behavior in -various addressing cases and their effect on network traffic. The -specifics of NAT behavior are not commonly documented by vendors of -equipment containing NAT implementations. - -The computers on an internal network can use any of the addresses set -aside by the :abbr:`IANA (Internet Assigned Numbers Authority)` for -private addressing (see :rfc:`1918`). These reserved IP addresses are -not in use on the Internet, so an external machine will not directly -route to them. The following addresses are reserved for private use: - -* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) -* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) -* 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) - - -If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses -:rfc:`1918` address space to number customer gateways, the risk of -address collision, and therefore routing failures, arises when the -customer network already uses an :rfc:`1918` address space. - -This prompted some ISPs to develop a policy within the :abbr:`ARIN -(American Registry for Internet Numbers)` to allocate new private -address space for CGNs, but ARIN deferred to the IETF before -implementing the policy indicating that the matter was not a typical -allocation issue but a reservation of addresses for technical purposes -(per :rfc:`2860`). - -IETF published :rfc:`6598`, detailing a shared address space for use in -ISP CGN deployments that can handle the same network prefixes occurring -both on inbound and outbound interfaces. ARIN returned address space to -the :abbr:`IANA (Internet Assigned Numbers Authority)` for this -allocation. - -The allocated address block is 100.64.0.0/10. - -Devices evaluating whether an IPv4 address is public must be updated to -recognize the new address space. Allocating more private IPv4 address -space for NAT devices might prolong the transition to IPv6. - -Overview -======== - -Different NAT Types -------------------- - -.. _source-nat: - -SNAT -^^^^ - -:abbr:`SNAT (Source Network Address Translation)` is the most common -form of :abbr:`NAT (Network Address Translation)` and is typically -referred to simply as NAT. To be more correct, what most people refer -to as :abbr:`NAT (Network Address Translation)` is actually the process -of :abbr:`PAT (Port Address Translation)`, or NAT overload. SNAT is -typically used by internal users/private hosts to access the Internet -- the source address is translated and thus kept private. - -.. _destination-nat: - -DNAT -^^^^ - -:abbr:`DNAT (Destination Network Address Translation)` changes the -destination address of packets passing through the router, while -:ref:`source-nat` changes the source address of packets. DNAT is -typically used when an external (public) host needs to initiate a -session with an internal (private) host. A customer needs to access a -private service behind the routers public IP. A connection is -established with the routers public IP address on a well known port and -thus all traffic for this port is rewritten to address the internal -(private) host. - -.. _bidirectional-nat: - -Bidirectional NAT -^^^^^^^^^^^^^^^^^ - -This is a common scenario where both :ref:`source-nat` and -:ref:`destination-nat` are configured at the same time. It's commonly -used then internal (private) hosts need to establish a connection with -external resources and external systems need to access internal -(private) resources. - -NAT, Routing, Firewall Interaction ----------------------------------- - -There is a very nice picture/explanation in the Vyatta documentation -which should be rewritten here. - -NAT Ruleset ------------ - -:abbr:`NAT (Network Address Translation)` is configured entirely on a -series of so called `rules`. Rules are numbered and evaluated by the -underlying OS in numerical order! The rule numbers can be changes by -utilizing the :cfgcmd:`rename` and :cfgcmd:`copy` commands. - -.. note:: Changes to the NAT system only affect newly established - connections. Already established connections are not affected. - -.. hint:: When designing your NAT ruleset leave some space between - consecutive rules for later extension. Your ruleset could start with - numbers 10, 20, 30. You thus can later extend the ruleset and place - new rules between existing ones. - -Rules will be created for both :ref:`source-nat` and -:ref:`destination-nat`. - -For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and -:ref:`destination-nat` needs to be created. - -.. _traffic-filters: - -Traffic Filters ---------------- - -Traffic Filters are used to control which packets will have the defined -NAT rules applied. Five different filters can be applied within a NAT -rule. - -* **outbound-interface** - applicable only to :ref:`source-nat`. It - configures the interface which is used for the outside traffic that - this translation rule applies to. - - Example: - - .. code-block:: none - - set nat source rule 20 outbound-interface eth0 - -* **inbound-interface** - applicable only to :ref:`destination-nat`. It - configures the interface which is used for the inside traffic the - translation rule applies to. - - Example: - - .. code-block:: none - - set nat destination rule 20 inbound-interface eth1 - -* **protocol** - specify which types of protocols this translation rule - applies to. Only packets matching the specified protocol are NATed. By default this - applies to `all` protocols. - - Example: - - * Set SNAT rule 20 to only NAT TCP and UDP packets - * Set DNAT rule 20 to only NAT UDP packets - - .. code-block:: none - - set nat source rule 20 protocol tcp_udp - set nat destination rule 20 protocol udp - -* **source** - specifies which packets the NAT translation rule applies - to based on the packets source IP address and/or source port. Only - matching packets are considered for NAT. - - Example: - - * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 - network - * Set SNAT rule 30 to only NAT packets arriving from the 192.0.3.0/24 - network with a source port of 80 and 443 - - .. code-block:: none - - set nat source rule 20 source address 192.0.2.0/24 - set nat source rule 30 source address 192.0.3.0/24 - set nat source rule 30 source port 80,443 - - -* **destination** - specify which packets the translation will be - applied to, only based on the destination address and/or port number - configured. - - .. note:: If no destination is specified the rule will match on any - destination address and port. - - Example: - - * Configure SNAT rule (40) to only NAT packets with a destination - address of 192.0.2.1. - - .. code-block:: none - - set nat source rule 40 destination address 192.0.2.1 - - -Address Conversion ------------------- - -Every NAT rule has a translation command defined. The address defined -for the translation is the address used when the address information in -a packet is replaced. - -Source Address -^^^^^^^^^^^^^^ - -For :ref:`source-nat` rules the packets source address will be replaced -with the address specified in the translation command. A port -translation can also be specified and is part of the translation -address. - -.. note:: The translation address must be set to one of the available - addresses on the configured `outbound-interface` or it must be set to - `masquerade` which will use the primary IP address of the - `outbound-interface` as its translation address. - -.. note:: When using NAT for a large number of host systems it - recommended that a minimum of 1 IP address is used to NAT every 256 - private host systems. This is due to the limit of 65,000 port numbers - available for unique translations and a reserving an average of - 200-300 sessions per host system. - -Example: - -* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 -* Use address `masquerade` (the interfaces primary address) on rule 30 -* For a large amount of private machines behind the NAT your address - pool might to be bigger. Use any address in the range 100.64.0.10 - - 100.64.0.20 on SNAT rule 40 when doing the translation - - -.. code-block:: none - - set nat source rule 20 translation address 100.64.0.1 - set nat source rule 30 translation address 'masquerade' - set nat source rule 40 translation address 100.64.0.10-100.64.0.20 - - -Destination Address -^^^^^^^^^^^^^^^^^^^ - -For :ref:`destination-nat` rules the packets destination address will be -replaced by the specified address in the `translation address` command. - -Example: - -* DNAT rule 10 replaces the destination address of an inbound packet - with 192.0.2.10 - -.. code-block:: none - - set nat destination rule 10 translation address 192.0.2.10 - - -Configuration Examples -====================== - -To setup SNAT, we need to know: - -* The internal IP addresses we want to translate -* The outgoing interface to perform the translation on -* The external IP address to translate to - -In the example used for the Quick Start configuration above, we -demonstrate the following configuration: - -.. code-block:: none - - set nat source rule 100 outbound-interface 'eth0' - set nat source rule 100 source address '192.168.0.0/24' - set nat source rule 100 translation address 'masquerade' - -Which generates the following configuration: - -.. code-block:: none - - rule 100 { - outbound-interface eth0 - source { - address 192.168.0.0/24 - } - translation { - address masquerade - } - } - -In this example, we use **masquerade** as the translation address -instead of an IP address. The **masquerade** target is effectively an -alias to say "use whatever IP address is on the outgoing interface", -rather than a statically configured IP address. This is useful if you -use DHCP for your outgoing interface and do not know what the external -address will be. - -When using NAT for a large number of host systems it recommended that a -minimum of 1 IP address is used to NAT every 256 host systems. This is -due to the limit of 65,000 port numbers available for unique -translations and a reserving an average of 200-300 sessions per host -system. - -Example: For an ~8,000 host network a source NAT pool of 32 IP addresses -is recommended. - -A pool of addresses can be defined by using a hyphen between two IP -addresses: - -.. code-block:: none - - set nat source rule 100 translation address '203.0.113.32-203.0.113.63' - -.. _avoidng_leaky_nat: - -Avoiding "leaky" NAT --------------------- - -Linux netfilter will not NAT traffic marked as INVALID. This often -confuses people into thinking that Linux (or specifically VyOS) has a -broken NAT implementation because non-NATed traffic is seen leaving an -external interface. This is actually working as intended, and a packet -capture of the "leaky" traffic should reveal that the traffic is either -an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems -after Linux netfilter considers the connection closed. The most common -is the additional TCP RST some host implementations send after -terminating a connection (which is implementation-specific). - -In other words, connection tracking has already observed the connection -be closed and has transition the flow to INVALID to prevent attacks from -attempting to reuse the connection. - -You can avoid the "leaky" behavior by using a firewall policy that drops -"invalid" state packets. - -Having control over the matching of INVALID state traffic, e.g. the -ability to selectively log, is an important troubleshooting tool for -observing broken protocol behavior. For this reason, VyOS does not -globally drop invalid state traffic, instead allowing the operator to -make the determination on how the traffic is handled. - -.. _hairpin_nat_reflection: - -Hairpin NAT/NAT Reflection --------------------------- - -A typical problem with using NAT and hosting public servers is the -ability for internal systems to reach an internal server using it's -external IP address. The solution to this is usually the use of -split-DNS to correctly point host systems to the internal address when -requests are made internally. Because many smaller networks lack DNS -infrastructure, a work-around is commonly deployed to facilitate the -traffic by NATing the request from internal hosts to the source address -of the internal interface on the firewall. - -This technique is commonly referred to as NAT Reflection or Hairpin NAT. - -Example: - -* Redirect Microsoft RDP traffic from the outside (WAN, external) world - via :ref:`destination-nat` in rule 100 to the internal, private host - 192.0.2.40. - -* Redirect Microsoft RDP traffic from the internal (LAN, private) - network via :ref:`destination-nat` in rule 110 to the internal, - private host 192.0.2.40. We also need a :ref:`source-nat` rule 110 for - the reverse path of the traffic. The internal network 192.0.2.0/24 is - reachable via interface `eth0.10`. - -.. code-block:: none - - set nat destination rule 100 description 'Regular destination NAT from external' - set nat destination rule 100 destination port '3389' - set nat destination rule 100 inbound-interface 'pppoe0' - set nat destination rule 100 protocol 'tcp' - set nat destination rule 100 translation address '192.0.2.40' - - set nat destination rule 110 description 'NAT Reflection: INSIDE' - set nat destination rule 110 destination port '3389' - set nat destination rule 110 inbound-interface 'eth0.10' - set nat destination rule 110 protocol 'tcp' - set nat destination rule 110 translation address '192.0.2.40' - - set nat source rule 110 description 'NAT Reflection: INSIDE' - set nat source rule 110 destination address '192.0.2.0/24' - set nat source rule 110 outbound-interface 'eth0.10' - set nat source rule 110 protocol 'tcp' - set nat source rule 110 source address '192.0.2.0/24' - set nat source rule 110 translation address 'masquerade' - -Which results in a configuration of: - -.. code-block:: none - - vyos@vyos# show nat - destination { - rule 100 { - description "Regular destination NAT from external" - destination { - port 3389 - } - inbound-interface pppoe0 - protocol tcp - translation { - address 192.0.2.40 - } - } - rule 110 { - description "NAT Reflection: INSIDE" - destination { - port 3389 - } - inbound-interface eth0.10 - protocol tcp - translation { - address 192.0.2.40 - } - } - } - source { - rule 110 { - description "NAT Reflection: INSIDE" - destination { - address 192.0.2.0/24 - } - outbound-interface eth0.10 - protocol tcp - source { - address 192.0.2.0/24 - } - translation { - address masquerade - } - } - } - - -Destination NAT ---------------- - -DNAT is typically referred to as a **Port Forward**. When using VyOS as -a NAT router and firewall, a common configuration task is to redirect -incoming traffic to a system behind the firewall. - -In this example, we will be using the example Quick Start configuration -above as a starting point. - -To setup a destination NAT rule we need to gather: - -* The interface traffic will be coming in on; -* The protocol and port we wish to forward; -* The IP address of the internal system we wish to forward traffic to. - -In our example, we will be forwarding web server traffic to an internal -web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol -on port 80. For other common port numbers, see: -https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers - -Our configuration commands would be: - -.. code-block:: none - - set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' - set nat destination rule 10 destination port '80' - set nat destination rule 10 inbound-interface 'eth0' - set nat destination rule 10 protocol 'tcp' - set nat destination rule 10 translation address '192.168.0.100' - -Which would generate the following NAT destination configuration: - -.. code-block:: none - - nat { - destination { - rule 10 { - description "Port Forward: HTTP to 192.168.0.100" - destination { - port 80 - } - inbound-interface eth0 - protocol tcp - translation { - address 192.168.0.100 - } - } - } - } - -.. note:: If forwarding traffic to a different port than it is arriving - on, you may also configure the translation port using - `set nat destination rule [n] translation port`. - -This establishes our Port Forward rule, but if we created a firewall -policy it will likely block the traffic. - -It is important to note that when creating firewall rules that the DNAT -translation occurs **before** traffic traverses the firewall. In other -words, the destination address has already been translated to -192.168.0.100. - -So in our firewall policy, we want to allow traffic coming in on the -outside interface, destined for TCP port 80 and the IP address of -192.168.0.100. - -.. code-block:: none - - set firewall name OUTSIDE-IN rule 20 action 'accept' - set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100' - set firewall name OUTSIDE-IN rule 20 destination port '80' - set firewall name OUTSIDE-IN rule 20 protocol 'tcp' - set firewall name OUTSIDE-IN rule 20 state new 'enable' - -This would generate the following configuration: - -.. code-block:: none - - rule 20 { - action accept - destination { - address 192.168.0.100 - port 80 - } - protocol tcp - state { - new enable - } - } - -.. note:: - - If you have configured the `INSIDE-OUT` policy, you will need to add - additional rules to permit inbound NAT traffic. - -1-to-1 NAT ----------- - -Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT -configuration, both DNAT and SNAT are used to NAT all traffic from an -external IP address to an internal IP address and vice-versa. - -Typically, a 1-to-1 NAT rule omits the destination port (all ports) and -replaces the protocol with either **all** or **ip**. - -Then a corresponding SNAT rule is created to NAT outgoing traffic for -the internal IP to a reserved external IP. This dedicates an external IP -address to an internal IP address and is useful for protocols which -don't have the notion of ports, such as GRE. - -Here's an extract of a simple 1-to-1 NAT configuration with one internal -and one external interface: - -.. code-block:: none - - set interfaces ethernet eth0 address '192.168.1.1/24' - set interfaces ethernet eth0 description 'Inside interface' - set interfaces ethernet eth1 address '192.0.2.30/24' - set interfaces ethernet eth1 description 'Outside interface' - set nat destination rule 2000 description '1-to-1 NAT example' - set nat destination rule 2000 destination address '192.0.2.30' - set nat destination rule 2000 inbound-interface 'eth1' - set nat destination rule 2000 translation address '192.168.1.10' - set nat source rule 2000 description '1-to-1 NAT example' - set nat source rule 2000 outbound-interface 'eth1' - set nat source rule 2000 source address '192.168.1.10' - set nat source rule 2000 translation address '192.0.2.30' - -Firewall rules are written as normal, using the internal IP address as -the source of outbound rules and the destination of inbound rules. - -NAT before VPN --------------- - -Some application service providers (ASPs) operate a VPN gateway to -provide access to their internal resources, and require that a -connecting organisation translate all traffic to the service provider -network to a source address provided by the ASP. - -Example Network -^^^^^^^^^^^^^^^ - -Here's one example of a network environment for an ASP. -The ASP requests that all connections from this company should come from -172.29.41.89 - an address that is assigned by the ASP and not in use at -the customer site. - -.. figure:: _static/images/nat_before_vpn_topology.png - :scale: 100 % - :alt: NAT before VPN Topology - - NAT before VPN Topology - - -Configuration -^^^^^^^^^^^^^ - -The required configuration can be broken down into 4 major pieces: - -* A dummy interface for the provider-assigned IP; -* NAT (specifically, Source NAT); -* IPSec IKE and ESP Groups; -* IPSec VPN tunnels. - - -Dummy interface -""""""""""""""" - -The dummy interface allows us to have an equivalent of the Cisco IOS -Loopback interface - a router-internal interface we can use for IP -addresses the router must know about, but which are not actually -assigned to a real network. - -We only need a single step for this interface: - -.. code-block:: none - - set interfaces dummy dum0 address '172.29.41.89/32' - -NAT Configuration -""""""""""""""""" - -.. code-block:: none - - set nat source rule 110 description 'Internal to ASP' - set nat source rule 110 destination address '172.27.1.0/24' - set nat source rule 110 outbound-interface 'any' - set nat source rule 110 source address '192.168.43.0/24' - set nat source rule 110 translation address '172.29.41.89' - set nat source rule 120 description 'Internal to ASP' - set nat source rule 120 destination address '10.125.0.0/16' - set nat source rule 120 outbound-interface 'any' - set nat source rule 120 source address '192.168.43.0/24' - set nat source rule 120 translation address '172.29.41.89' - -IPSec IKE and ESP -""""""""""""""""" - -The ASP has documented their IPSec requirements: - -* IKE Phase: - - * aes256 Encryption - * sha256 Hashes - -* ESP Phase: - - * aes256 Encryption - * sha256 Hashes - * DH Group 14 - - -Additionally, we want to use VPNs only on our eth1 interface (the -external interface in the image above) - -.. code-block:: none - - set vpn ipsec ike-group my-ike ikev2-reauth 'no' - set vpn ipsec ike-group my-ike key-exchange 'ikev1' - set vpn ipsec ike-group my-ike lifetime '7800' - set vpn ipsec ike-group my-ike proposal 1 dh-group '14' - set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' - set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' - - set vpn ipsec esp-group my-esp compression 'disable' - set vpn ipsec esp-group my-esp lifetime '3600' - set vpn ipsec esp-group my-esp mode 'tunnel' - set vpn ipsec esp-group my-esp pfs 'disable' - set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' - set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' - - set vpn ipsec ipsec-interfaces interface 'eth1' - -IPSec VPN Tunnels -""""""""""""""""" - -We'll use the IKE and ESP groups created above for this VPN. Because we -need access to 2 different subnets on the far side, we will need two -different tunnels. If you changed the names of the ESP group and IKE -group in the previous step, make sure you use the correct names here -too. - -.. code-block:: none - - set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' - set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' - set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' - set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' - set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' - -Testing and Validation -"""""""""""""""""""""" - -If you've completed all the above steps you no doubt want to see if it's -all working. - -Start by checking for IPSec SAs (Security Associations) with: - -.. code-block:: none - - $ show vpn ipsec sa - - Peer ID / IP Local ID / IP - ------------ ------------- - 198.51.100.243 203.0.113.46 - - Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto - ------ ----- ------------- ------- ---- ----- ------ ------ ----- - 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all - 1 up 0.0/0.0 aes256 sha256 no 865 3600 all - -That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/nptv6.rst b/docs/nptv6.rst deleted file mode 100644 index f4e08325..00000000 --- a/docs/nptv6.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. include:: _include/need_improvement.txt - -.. _nptv6: - -##### -NPTv6 -##### - -:abbr:`NPTv6 (Network Prefix Translation)` is a form of NAT for IPv6. It's -described in :rfc:`6296`. - -**Usage** - -NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the -external IPv6 prefix is dynamic, as it prevents the need for renumbering of -internal hosts when the extern prefix changes. - -Let's assume the following network configuration: - -* eth0 : LAN -* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it -* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it - -Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over -2001:db8:e2::/48? What happens when you get a new provider with a different -routed IPv6 subnet? - -The solution here is to assign to your hosts ULAs_ and to prefix-translate -their address to the right subnet when going through your router. - -* LAN Subnet : fc00:dead:beef::/48 -* WAN 1 Subnet : 2001:db8:e1::/48 -* WAN 2 Subnet : 2001:db8:e2::/48 - -* eth0 addr : fc00:dead:beef::1/48 -* eth1 addr : 2001:db8:e1::1/48 -* eth2 addr : 2001:db8:e2::1/48 - -VyOS Support -^^^^^^^^^^^^ - -NPTv6 support has been added in VyOS 1.2 (Crux) and is available through -`nat nptv6` configuration nodes. - -.. code-block:: none - - set rule 10 source prefix 'fc00:dead:beef::/48' - set rule 10 outbound-interface 'eth1' - set rule 10 translation prefix '2001:db8:e1::/48' - set rule 20 source prefix 'fc00:dead:beef::/48' - set rule 20 outbound-interface 'eth2' - set rule 20 translation prefix '2001:db8:e2::/48' - -Resulting in the following ip6tables rules: - -.. code-block:: none - - Chain VYOS_DNPT_HOOK (1 references) - pkts bytes target prot opt in out source destination - 0 0 NETMAP all eth1 any anywhere 2001:db8:e1::/48 to:fc00:dead:beef::/48 - 0 0 NETMAP all eth2 any anywhere 2001:db8:e2::/48 to:fc00:dead:beef::/48 - 0 0 RETURN all any any anywhere anywhere - Chain VYOS_SNPT_HOOK (1 references) - pkts bytes target prot opt in out source destination - 0 0 NETMAP all any eth1 fc00:dead:beef::/48 anywhere to:2001:db8:e1::/48 - 0 0 NETMAP all any eth2 fc00:dead:beef::/48 anywhere to:2001:db8:e2::/48 - 0 0 RETURN all any any anywhere anywhere - -.. _ULAs: https://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst deleted file mode 100644 index 7b0341cb..00000000 --- a/docs/routing/pbr.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _routing-pbr: - -### -PBR -### - -:abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to -different routing tables. Traffic can be matched using standard 5-tuple -matching (source address, destination address, protocol, source port, -destination port). - -Transparent Proxy -================= - -The following example will show how VyOS can be used to redirect web -traffic to an external transparent proxy: - -.. code-block:: none - - set policy route FILTER-WEB rule 1000 destination port 80 - set policy route FILTER-WEB rule 1000 protocol tcp - set policy route FILTER-WEB rule 1000 set table 100 - -This creates a route policy called FILTER-WEB with one rule to set the -routing table for matching traffic (TCP port 80) to table ID 100 -instead of the default routing table. - -To create routing table 100 and add a new default gateway to be used by -traffic matching our route policy: - -.. code-block:: none - - set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 - -This can be confirmed using the ``show ip route table 100`` operational -command. - -Finally, to apply the policy route to ingress traffic on our LAN -interface, we use: - -.. code-block:: none - - set interfaces ethernet eth1 policy route FILTER-WEB - - -Multiple Uplinks -================ - -VyOS Policy-Based Routing (PBR) works by matching source IP address -ranges and forwarding the traffic using different routing tables. - -Routing tables that will be used in this example are: - -* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24) -* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24) -* ``main`` Routing table used by VyOS and other interfaces not - participating in PBR - -.. figure:: ../_static/images/pbr_example_1.png - :scale: 80 % - :alt: PBR multiple uplinks - - Policy-Based Routing with multiple ISP uplinks - (source ./draw.io/pbr_example_1.drawio) - -Add default routes for routing ``table 10`` and ``table 11`` - -.. code-block:: none - - set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1 - set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 - -Add policy route matching VLAN source addresses - -.. code-block:: none - - set policy route PBR rule 20 set table '10' - set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' - set policy route PBR rule 20 source address '192.168.188.0/24' - - set policy route PBR rule 30 set table '11' - set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' - set policy route PBR rule 30 source address '192.168.189.0/24' - -Apply routing policy to **inbound** direction of out VLAN interfaces - -.. code-block:: none - - set interfaces ethernet eth0 vif 10 policy route 'PBR' - set interfaces ethernet eth0 vif 11 policy route 'PBR' - - -**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) -from PBR - -.. code-block:: none - - set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' - set policy route PBR rule 10 destination address '192.168.188.0/24' - set policy route PBR rule 10 destination address '192.168.189.0/24' - set policy route PBR rule 10 set table 'main' - -These commands allow the VLAN10 and VLAN20 hosts to communicate with -each other using the main routing table. - -Local route -=========== - -The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` for traffic, which originated from the router itself. -That solution for multiple ISP's and VyOS router will respond from the same interface that the packet was received. -Also, it used, if we want that one VPN tunnel to be through one provider, and the second through another. - -* ``192.168.1.254`` IP addreess on VyOS eth1 from ISP1 -* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2 -* ``table 10`` Routing table used for ISP1 -* ``table 11`` Routing table used for ISP2 - - -.. code-block:: none - - set policy local-route rule 101 set table '10' - set policy local-route rule 101 source '192.0.1.254' - set policy local-route rule 102 set table '11' - set policy local-route rule 102 source '192.0.2.254' - set protocols static table 10 route '0.0.0.0/0' next-hop '192.0.1.1' - set protocols static table 11 route '0.0.0.0/0' next-hop '192.0.2.2' - -Add multiple source IP in one rule with same priority - -.. code-block:: none - - set policy local-route rule 101 set table '10' - set policy local-route rule 101 source '192.0.1.254' - set policy local-route rule 101 source '192.0.1.253' - set policy local-route rule 101 source '203.0.113.0/24' diff --git a/docs/routing/policy.rst b/docs/routing/policy.rst deleted file mode 100644 index 4eeb40d6..00000000 --- a/docs/routing/policy.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -###### -Policy -###### - -Routing Policies could be used to tell the router (self or neighbors) what -routes and their attributes needs to be put into the routing table. - -There could be a wide range of routing policies. Some examples are below: - -* Set some metric to routes learned from a particular neighbor -* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors -* Prefer a specific routing protocol routes over another routing protocol running on the same router - -Example -======= - -**Policy definition:** - -.. code-block:: none - - # Create policy - set policy route-map setmet rule 2 action 'permit' - set policy route-map setmet rule 2 set as-path-prepend '2 2 2' - - # Apply policy to BGP - set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' - set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' - -Using 'soft-reconfiguration' we get the policy update without bouncing the -neighbor. - -**Routes learned before routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ show ip bgp - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - - Total number of prefixes 1 - -**Routes learned after routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ sho ip b - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i - - Total number of prefixes 1 - vyos@vos1:~$ - -You now see the longer AS path. -- cgit v1.2.3 From 4abded8025a47990e58cd0a5fe9b96e38f4a3715 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:52:28 +0100 Subject: arrange: interfaces --- Pipfile | 16 + docs/configuration/interfaces/bonding.rst | 560 +++++++++++++++++++++ docs/configuration/interfaces/bridge.rst | 270 ++++++++++ docs/configuration/interfaces/dummy.rst | 79 +++ docs/configuration/interfaces/ethernet.rst | 226 +++++++++ docs/configuration/interfaces/geneve.rst | 61 +++ docs/configuration/interfaces/index.rst | 28 ++ docs/configuration/interfaces/l2tpv3.rst | 192 +++++++ docs/configuration/interfaces/loopback.rst | 71 +++ docs/configuration/interfaces/macsec.rst | 191 +++++++ docs/configuration/interfaces/openvpn.rst | 584 ++++++++++++++++++++++ docs/configuration/interfaces/pppoe.rst | 307 ++++++++++++ docs/configuration/interfaces/pseudo-ethernet.rst | 65 +++ docs/configuration/interfaces/tunnel.rst | 216 ++++++++ docs/configuration/interfaces/vti.rst | 22 + docs/configuration/interfaces/vxlan.rst | 295 +++++++++++ docs/configuration/interfaces/wireguard.rst | 265 ++++++++++ docs/configuration/interfaces/wireless.rst | 573 +++++++++++++++++++++ docs/configuration/interfaces/wirelessmodem.rst | 128 +++++ docs/interfaces/bond.rst | 560 --------------------- docs/interfaces/bridge.rst | 270 ---------- docs/interfaces/dummy.rst | 79 --- docs/interfaces/ethernet.rst | 226 --------- docs/interfaces/geneve.rst | 61 --- docs/interfaces/l2tpv3.rst | 192 ------- docs/interfaces/loopback.rst | 71 --- docs/interfaces/macsec.rst | 191 ------- docs/interfaces/pppoe.rst | 307 ------------ docs/interfaces/pseudo-ethernet.rst | 65 --- docs/interfaces/tunnel.rst | 235 --------- docs/interfaces/vxlan.rst | 295 ----------- docs/interfaces/wireless.rst | 573 --------------------- docs/interfaces/wirelessmodem.rst | 128 ----- docs/vpn/openvpn.rst | 584 ---------------------- docs/vpn/wireguard.rst | 265 ---------- 35 files changed, 4149 insertions(+), 4102 deletions(-) create mode 100644 Pipfile create mode 100644 docs/configuration/interfaces/bonding.rst create mode 100644 docs/configuration/interfaces/bridge.rst create mode 100644 docs/configuration/interfaces/dummy.rst create mode 100644 docs/configuration/interfaces/ethernet.rst create mode 100644 docs/configuration/interfaces/geneve.rst create mode 100644 docs/configuration/interfaces/index.rst create mode 100644 docs/configuration/interfaces/l2tpv3.rst create mode 100644 docs/configuration/interfaces/loopback.rst create mode 100644 docs/configuration/interfaces/macsec.rst create mode 100644 docs/configuration/interfaces/openvpn.rst create mode 100644 docs/configuration/interfaces/pppoe.rst create mode 100644 docs/configuration/interfaces/pseudo-ethernet.rst create mode 100644 docs/configuration/interfaces/tunnel.rst create mode 100644 docs/configuration/interfaces/vti.rst create mode 100644 docs/configuration/interfaces/vxlan.rst create mode 100644 docs/configuration/interfaces/wireguard.rst create mode 100644 docs/configuration/interfaces/wireless.rst create mode 100644 docs/configuration/interfaces/wirelessmodem.rst delete mode 100644 docs/interfaces/bond.rst delete mode 100644 docs/interfaces/bridge.rst delete mode 100644 docs/interfaces/dummy.rst delete mode 100644 docs/interfaces/ethernet.rst delete mode 100644 docs/interfaces/geneve.rst delete mode 100644 docs/interfaces/l2tpv3.rst delete mode 100644 docs/interfaces/loopback.rst delete mode 100644 docs/interfaces/macsec.rst delete mode 100644 docs/interfaces/pppoe.rst delete mode 100644 docs/interfaces/pseudo-ethernet.rst delete mode 100644 docs/interfaces/tunnel.rst delete mode 100644 docs/interfaces/vxlan.rst delete mode 100644 docs/interfaces/wireless.rst delete mode 100644 docs/interfaces/wirelessmodem.rst delete mode 100644 docs/vpn/openvpn.rst delete mode 100644 docs/vpn/wireguard.rst (limited to 'docs/configuration') diff --git a/Pipfile b/Pipfile new file mode 100644 index 00000000..423092c4 --- /dev/null +++ b/Pipfile @@ -0,0 +1,16 @@ +[[source]] +url = "https://pypi.org/simple" +verify_ssl = true +name = "pypi" + +[packages] +sphinx-rtd-theme = "*" +docutils = "*" +lxml = "*" +sphinx-notfound-page = "*" +Sphinx = ">=1.4.3" + +[dev-packages] + +[requires] +python_version = "3.9" diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..7faddd6f --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,560 @@ +.. _bond-interface: + +####################### +Bond / Link Aggregation +####################### + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bonding member interface + + Enslave `` interface to bond ``. + +Bond options +============ + +.. cfgcmd:: set interfaces bonding mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the :cfgcmd:`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet mis-ordering requirements of section 43.2.4 + of the 802.3ad standard. + + * ``active-backup`` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The :cfgcmd:`primary` option, + documented below, affects the behavior of this mode. + + * ``broadcast`` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * ``round-robin`` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * ``adaptive-load-balance`` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause carrier to be asserted (for 802.3ad + mode) whenever there is an active aggregator, regardless of the number of + available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. + +.. cfgcmd:: set interfaces bonding hash-policy + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet this criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding primary + + An `` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding arp-monitor interval