vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add load-balancing reverse-proxy documentation and examples

Browse Source
This commit is contained in:
Viacheslav Hletenko 2023-05-24 19:08:22 +03:00
parent 38e576b16b
commit 8a788bf32d
3 changed files with 612 additions and 311 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

319
docs/configuration/loadbalancing/index.rst
View File

@ -1,315 +1,12 @@
:lastproofread: 2023-01-27
.. _load-balancing: .. _load-balancing:
WAN load balancing ##############
================== Load-balancing
##############
Outbound traffic can be balanced between two or more outbound interfaces. .. toctree::
If a path fails, traffic is balanced across the remaining healthy paths, :maxdepth: 1
a recovered path is automatically added back to the routing table and used by :includehidden:
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.
wan
In a minimal configuration, the following must be provided: reverse-proxy
* 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

289
docs/configuration/loadbalancing/reverse-proxy.rst Normal file
View File

@ -0,0 +1,289 @@
.. _load-balancing:
#############
Reverse-proxy
#############
.. include:: /_include/need_improvement.txt
VyOS reverse-proxy is balancer and proxy server that provides
high-availability, load balancing and proxying for TCP (level 4)
and HTTP-based (level 7) applications.
Configuration
=============
Service configuration is responsible for binding to a specific port,
while the backend configuration determines the type of load balancing
to be applied and specifies the real servers to be utilized.
Service
-------
.. cfgcmd:: set load-balancing reverse-proxy service <name> listen-address
<address>
Set service to bind on IP address, by default listen on any IPv4 and IPv6
.. cfgcmd:: set load-balancing reverse-proxy service <name> port
<port>
Create service `<name>` to listen on <port>
.. cfgcmd:: set load-balancing reverse-proxy service <name> mode
<tcp|http>
Configure service `<name>` mode TCP or HTTP
.. cfgcmd:: set load-balancing reverse-proxy service <name> backend
<name>
Configure service `<name>` to use the backend <name>
.. cfgcmd:: set load-balancing reverse-proxy service <name> ssl
certificate <name>
Set SSL certeficate <name> for service <name>
Rules
^^^^^
Rules allow to control and route incoming traffic to specific backend based
on predefined conditions. Rules allow to define matching criteria and
perform action accordingly.
.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
domain-name <name>
Match domain name
.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
ssl <sni>
SSL match Server Name Indication (SNI) option:
* ``req-ssl-sni`` SSL Server Name Indication (SNI) request match
* ``ssl-fc-sni`` SSL frontend connection Server Name Indication match
* ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name
Indication
.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
url-path <match> <url>
Allows to define URL path matching rules for a specific service.
With this command, you can specify how the URL path should be matched
against incoming requests.
The available options for <match> are:
* ``begin`` Matches the beginning of the URL path
* ``end`` Matches the end of the URL path.
* ``exact`` Requires an exactly match of the URL path
.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
set backend <name>
Assign a specific backend to a rule
.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
redirect-location <url>
Redirect URL to a new location
Backend
-------
.. cfgcmd:: set load-balancing reverse-proxy backend <name> balance
<balance>
Load-balancing algorithms to be used for distributind requests among the
vailable servers
Balance algorithms:
* ``source-address`` Distributes requests based on the source IP address
of the client
* ``round-robin`` Distributes requests in a circular manner,
sequentially sending each request to the next server in line
* ``least-connection`` Distributes requests tp tje server wotj the fewest
active connections
.. cfgcmd:: set load-balancing reverse-proxy backend <name> mode
<mode>
Configure backend `<name>` mode TCP or HTTP
.. cfgcmd:: set load-balancing reverse-proxy backend <name> parameters
http-check
Enable layer 7 HTTP health check
.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
<name> address <x.x.x.x>
Set the address of the backend server to which the incoming traffic will
be forwarded
.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
<name> port <port>
Set the address of the backend port
.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
<name> check
Active health check backend server
.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
<name> send-proxy
Send a Proxy Protocol version 1 header (text format)
.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
<name> send-proxy-v2
Send a Proxy Protocol version 2 header (binary format)
Gloabal
-------
Global parameters
.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections
<num>
Limit maximum number of connections
.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers
<ciphers>
Limit allowed cipher algorithms used during SSL/TLS handshake
.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min
<version>
Specify the minimum required TLS version 1.2 or 1.3
Redirect HTTP to HTTPS
======================
Configure the load-balancing reverse-proxy service for HTTP.
This configuration listen on port 80 and redirect incoming
requests to HTTPS:
.. code-block:: none
set load-balancing reverse-proxy service http port '80'
set load-balancing reverse-proxy service http redirect-http-to-https
The name of the service can be different, in this example it is only for
convenience.
Examples
========
Level 4 balancing
-----------------
This configuration enables the TCP reverse proxy for the "my-tcp-api" service.
Incoming TCP connections on port 8888 will be load balanced across the backend
servers (srv01 and srv02) using the round-robin load-balancing algorithm.
.. code-block:: none
set load-balancing reverse-proxy service my-tcp-api backend 'bk-01'
set load-balancing reverse-proxy service my-tcp-api mode 'tcp'
set load-balancing reverse-proxy service my-tcp-api port '8888'
set load-balancing reverse-proxy backend bk-01 balance 'round-robin'
set load-balancing reverse-proxy backend bk-01 mode 'tcp'
set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11'
set load-balancing reverse-proxy backend bk-01 server srv01 port '8881'
set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12'
set load-balancing reverse-proxy backend bk-01 server srv02 port '8882'
Balancing based on domain name
------------------------------
The following configuration demonstrates how to use VyOS
to achieve load balancing based on the domain name.
The HTTP service listen on TCP port 80.
Rule 10 matches requests with the domain name ``node1.example.com`` forwards
to the backend ``bk-api-01``
Rule 20 matches requests with the domain name ``node2.example.com`` forwards
to the backend ``bk-api-02``
.. code-block:: none
set load-balancing reverse-proxy service http description 'bind app listen on 443 port'
set load-balancing reverse-proxy service http mode 'tcp'
set load-balancing reverse-proxy service http port '80'
set load-balancing reverse-proxy service http rule 10 domain-name 'node1.example.com'
set load-balancing reverse-proxy service http rule 10 set backend 'bk-api-01'
set load-balancing reverse-proxy service http rule 20 domain-name 'node2.example.com'
set load-balancing reverse-proxy service http rule 20 set backend 'bk-api-02'
set load-balancing reverse-proxy backend bk-api-01 description 'My API-1'
set load-balancing reverse-proxy backend bk-api-01 mode 'tcp'
set load-balancing reverse-proxy backend bk-api-01 server api01 address '127.0.0.1'
set load-balancing reverse-proxy backend bk-api-01 server api01 port '4431'
set load-balancing reverse-proxy backend bk-api-02 description 'My API-2'
set load-balancing reverse-proxy backend bk-api-02 mode 'tcp'
set load-balancing reverse-proxy backend bk-api-02 server api01 address '127.0.0.2'
set load-balancing reverse-proxy backend bk-api-02 server api01 port '4432'
Terminate SSL
-------------
The following configuration reverse-proxy terminate SSL.
The ``http`` service is lestens on port 80 and force redirects from HTTP to
HTTPS.
The ``https`` service listens on port 443 with backend `bk-default` to
handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination.
Rule 10 matches requests with the exact URL path ``/.well-known/xxx``
and redirects to location ``/certs/``.
Rule 20 matches requests with URL paths ending in ``/mail`` or exact
path ``/email/bar`` redirect to location ``/postfix/``.
Additional global parameters are set, including the maximum number
connection limit of 4000 and a minimum TLS version of 1.3.
.. code-block:: none
set load-balancing reverse-proxy service http description 'Force redirect to HTTPS'
set load-balancing reverse-proxy service http port '80'
set load-balancing reverse-proxy service http redirect-http-to-https
set load-balancing reverse-proxy service https backend 'bk-default'
set load-balancing reverse-proxy service https description 'listen on 443 port'
set load-balancing reverse-proxy service https mode 'http'
set load-balancing reverse-proxy service https port '443'
set load-balancing reverse-proxy service https ssl certificate 'cert'
set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx'
set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/'
set load-balancing reverse-proxy service https rule 20 url-path end '/mail'
set load-balancing reverse-proxy service https rule 20 url-path exact '/email/bar'
set load-balancing reverse-proxy service https rule 20 set redirect-location '/postfix/'
set load-balancing reverse-proxy backend bk-default description 'Default backend'
set load-balancing reverse-proxy backend bk-default mode 'http'
set load-balancing reverse-proxy backend bk-default server sr01 address '192.0.2.23'
set load-balancing reverse-proxy backend bk-default server sr01 port '80'
set load-balancing reverse-proxy global-parameters max-connections '4000'
set load-balancing reverse-proxy global-parameters tls-version-min '1.3'

315
docs/configuration/loadbalancing/wan.rst Normal file
View File

@ -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