diff options
Diffstat (limited to 'docs/configuration/loadbalancing/wan.rst')
| -rw-r--r-- | docs/configuration/loadbalancing/wan.rst | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/docs/configuration/loadbalancing/wan.rst b/docs/configuration/loadbalancing/wan.rst new file mode 100644 index 00000000..18f01347 --- /dev/null +++ b/docs/configuration/loadbalancing/wan.rst @@ -0,0 +1,315 @@ +:lastproofread: 2023-01-27 + +.. _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: + + * an 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 + +.. note:: + + WAN Load Balacing should not be used when dynamic routing protocol is + used/needed. This feature creates customized routing tables and firewall + rules, that makes it incompatible to use with routing protocols. + +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, it 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 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% of traffic is routed to eth0, eth1 gets 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 <rule> limit <parameter> + +* ``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 <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 <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 <interface> + 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 the destination, ``ipv4-address`` can be set to +``dhcp`` + +.. code-block:: none + + set load-balancing wan interface-health <interface> nexthop <ipv4-address> + +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 <interface> failure-count <number> + set load-balancing wan interface-health <interface> success-count <number> + +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 <number> 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 |