diff options
| -rw-r--r-- | docs/configuration/loadbalancing/index.rst | 126 |
1 files changed, 85 insertions, 41 deletions
diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst index 6b0bede9..7d675c1b 100644 --- a/docs/configuration/loadbalancing/index.rst +++ b/docs/configuration/loadbalancing/index.rst @@ -4,8 +4,11 @@ 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. +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: @@ -26,9 +29,11 @@ Let's assume we have two DHCP WAN interfaces and one LAN (eth2): 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. +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: @@ -50,8 +55,10 @@ Create a load balancing rule, rule can be a number between 1 and 9999: 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. +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 @@ -63,15 +70,18 @@ Per default outbound traffic is distributed randomly across available interfaces 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: +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``. +* ``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. @@ -79,11 +89,15 @@ 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. +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: +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 @@ -92,7 +106,8 @@ Packet-based balancing can lead to a better balance across interfaces when out o Exclude traffic *************** -To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: +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 @@ -102,8 +117,11 @@ To exclude traffic from load balancing, traffic matching an exclude rule is not 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: +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 @@ -114,22 +132,26 @@ If an interface fails the health check it is removed from the load balancer's po success-count Success count +> test Rule number -Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` +Specify nexthop on the path to 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. +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: +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 @@ -141,17 +163,28 @@ For multi target health checking multiple tests can be defined: 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 +* ``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: +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 @@ -159,14 +192,16 @@ This works through automatically generated source NAT (SNAT) rules, these rules Sticky Connections ------------------ -Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. +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. +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 @@ -176,17 +211,23 @@ This can be achieved by enabling sticky connections in the load balancing: 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: +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: +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 @@ -194,12 +235,14 @@ Because existing sessions do not automatically fail over to a new path, the sess .. warning:: - Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. + 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: +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 @@ -212,7 +255,8 @@ Two environment variables are available: .. warning:: - Blocking call with no timeout. System will become unresponsive if script does not return! + Blocking call with no timeout. System will become unresponsive if script + does not return! Handling and monitoring ----------------------- |