diff options
Diffstat (limited to 'docs/configuration/loadbalancing')
| -rw-r--r-- | docs/configuration/loadbalancing/haproxy.md | 510 | ||||
| -rw-r--r-- | docs/configuration/loadbalancing/index.md | 15 | ||||
| -rw-r--r-- | docs/configuration/loadbalancing/wan.md | 306 |
3 files changed, 831 insertions, 0 deletions
diff --git a/docs/configuration/loadbalancing/haproxy.md b/docs/configuration/loadbalancing/haproxy.md new file mode 100644 index 00000000..d60c5248 --- /dev/null +++ b/docs/configuration/loadbalancing/haproxy.md @@ -0,0 +1,510 @@ +--- +lastproofread: '2026-04-06' +--- + +# HAproxy + +```{include} /_include/need_improvement.txt +``` + +HAProxy is a load 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 specifies the port to bind to. Backend +configuration defines the load balancing method and specifies the backend +servers. + +### Service + +```{cfgcmd} set load-balancing haproxy service \<name\> listen-address \<address\> + +Set the IP address for the service to bind to. By default, the service +listens on all IPv4 and IPv6 addresses. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> port \<port\> + +Create service *<name>* to listen on \<port\> +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> mode \<tcp|http\> + +Configure service *<name>* mode TCP or HTTP +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> backend \<name\> + +Configure service *<name>* to use the backend \<name\> +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> ssl certificate \<name\> + +Set the SSL certificate \<name\> for service \<name\>. You can define +multiple certificates. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> http-response-headers \<header-name\> value \<header-value\> + +Set custom HTTP headers to include in all responses. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> logging facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> timeout client \<seconds\> + +Set the maximum inactivity time on the client side for this service. +Value range 1-3600 seconds. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> http-compression algorithm \<gzip | deflate | identity | raw-deflate\> + +Set the compression algorithm to be used when compressing HTTP responses. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> http-compression mime-type \<mime-type\> + +Set the list of HTTP response MIME types which haproxy will attempt to +compress, if received uncompressed from backend server. +``` + +#### Rules + +Rules control and route incoming traffic to specific backends based on +predefined conditions. Rules define matching criteria and specify actions +to perform. + +```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> domain-name \<name\> + +Match domain name +``` + +````{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> ssl \<sni\> + +```{eval-rst} +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 haproxy service \<name\> rule \<rule\> url-path \<match\> \<url\> + +Define URL path matching rules for a specific service. Use this command +to specify how to match the URL path against incoming requests. + +```{eval-rst} +The available options for <match> are: + * ``begin`` Matches the beginning of the URL path + * ``end`` Matches the end of the URL path. + * ``exact`` Matches the URL path exactly. +``` +```` + +```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> set backend \<name\> + +Assign a specific backend to a rule +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> redirect-location \<url\> + +Redirect URL to a new location. +``` + +### Backend + +````{cfgcmd} set load-balancing haproxy backend \<name\> balance \<balance\> + +Specify the load balancing algorithm for distributing requests among +available servers. + +```{eval-rst} +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 to the server with the fewest + active connections. +``` +```` + +```{cfgcmd} set load-balancing haproxy backend \<name\> mode \<mode\> + +Configure backend *<name>* mode TCP or HTTP. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> address \<x.x.x.x\> + +Set the address of the backend server that receives incoming traffic. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> port \<port\> + +Set the address of the backend port. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> check + +Active health check backend server. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> check port \<port\> + +Set an alternative port number for health checks. +Overrides the default server port used for TCP/HTTP checks. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> send-proxy + +Send a Proxy Protocol version 1 header (text format). +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> send-proxy-v2 + +Send a Proxy Protocol version 2 header (binary format). +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> ssl ca-certificate \<ca-certificate\> + +Use SSL encryption for backend requests and authenticate the backend +against ``<ca-certificate>``. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> ssl no-verify + +Use SSL encryption for backend requests without validating the server +certificate. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-response-headers \<header-name\> value \<header-value\> + +Set custom HTTP headers to include in all responses from the backend. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> logging facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> timeout check \<seconds\> + +Set the timeout in seconds for established connections. +Value range 1-3600 seconds. +``` +```{cfgcmd} set load-balancing haproxy backend \<name\> timeout connect \<seconds\> + +Set the maximum time to wait for a connection attempt to a server to succeed. +Value range 1-3600 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy backend \<name\> timeout server \<seconds\> + +Set the maximum inactivity time on the server side. +Value range 1-3600 seconds. +``` + +### Global + +Global configuration parameters: + +```{cfgcmd} set load-balancing haproxy global-parameters max-connections \<num\> + +Limit maximum number of connections +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \<ciphers\> + +Limit the cipher algorithms allowed during SSL/TLS handshake. +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \<version\> + +Specify the minimum required TLS version 1.2 or 1.3 +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters logging facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + + +```{cfgcmd} set load-balancing haproxy timeout check \<seconds\> + +Set the timeout in seconds for established connections. +Value range 1-3600 seconds. Default is 5 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout client \<seconds\> + +Set the maximum inactivity time on the client side. +Value range 1-3600 seconds. Default is 50 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout connect \<seconds\> + +Set the maximum time to wait for a connection attempt to a server to succeed. +Value range 1-3600 seconds. Default is 10 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout server \<seconds\> + +Set the maximum inactivity time on the server side. +Value range 1-3600 seconds. Default is 50 seconds. +``` + +## Health checks + + +### HTTP checks + + +Use HTTP health checks to monitor web applications that provide health status +information and determine their availability. + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-check + +Enables HTTP health checks using OPTION HTTP requests against '/' and +expecting a successful response code in the 200-399 range. +``` + + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-check method \<method\> + +Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. +``` + + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-check uri \<path\> + +Set the endpoint to use for health checks. +``` + + +````{cfgcmd} set load-balancing haproxy backend \<name\> http-check expect \<condition\> + +Set the expected result condition for a server to be considered healthy. + +```{eval-rst} +Some possible examples are: + * ``status 200`` Expecting a 200 response code + * ``status 200-399`` Expecting a non-failure response code + * ``string success`` Expecting the string success in the response body +``` +```` + +### TCP checks + +Configure health checks for TCP mode backends. You can configure protocol-aware +checks for a range of Layer 7 protocols: + +````{cfgcmd} set load-balancing haproxy backend \<name\> health-check \<protocol\> + +```{eval-rst} +Available health check protocols: + * ``ldap`` LDAP protocol check. + * ``redis`` Redis protocol check. + * ``mysql`` MySQL protocol check. + * ``pgsql`` PostgreSQL protocol check. + * ``smtp`` SMTP protocol check. +``` +```` + +:::{note} +If you specify a server to check but do not configure a +protocol, HAProxy performs a basic TCP health check. A server is online if +it responds to a connection attempt with a valid `SYN/ACK` packet. +::: +## Redirect HTTP to HTTPS + +Configure a HAProxy service for HTTP that listens on port 80 and redirects +incoming requests to HTTPS: + +```none +set load-balancing haproxy service http port '80' +set load-balancing haproxy service http redirect-http-to-https +``` + +You can use a different service name; in this example, `http` is just 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 are load balanced across the +backend servers (srv01 and srv02) using the round-robin load balancing +algorithm. + +```none +set load-balancing haproxy service my-tcp-api backend 'bk-01' +set load-balancing haproxy service my-tcp-api mode 'tcp' +set load-balancing haproxy service my-tcp-api port '8888' + +set load-balancing haproxy backend bk-01 balance 'round-robin' +set load-balancing haproxy backend bk-01 mode 'tcp' + +set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing haproxy backend bk-01 server srv01 port '8881' +set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing haproxy 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 listens on TCP port 80. + +Rule 10 matches requests with the domain name `node1.example.com` and +forwards them to the backend `bk-api-01`. + +Rule 20 matches requests with the domain name `node2.example.com` and +forwards them to the backend `bk-api-02`. + +```none +set load-balancing haproxy service http description 'bind app listen on 443 port' +set load-balancing haproxy service http mode 'tcp' +set load-balancing haproxy service http port '80' + +set load-balancing haproxy service http rule 10 domain-name 'node1.example.com' +set load-balancing haproxy service http rule 10 set backend 'bk-api-01' +set load-balancing haproxy service http rule 20 domain-name 'node2.example.com' +set load-balancing haproxy service http rule 20 set backend 'bk-api-02' + +set load-balancing haproxy backend bk-api-01 description 'My API-1' +set load-balancing haproxy backend bk-api-01 mode 'tcp' +set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1' +set load-balancing haproxy backend bk-api-01 server api01 port '4431' +set load-balancing haproxy backend bk-api-02 description 'My API-2' +set load-balancing haproxy backend bk-api-02 mode 'tcp' +set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2' +set load-balancing haproxy backend bk-api-02 server api01 port '4432' +``` + +### Terminate SSL + +The following configuration terminates SSL on the router. + +The `http` service listens on port 80 and redirects HTTP requests to +HTTPS. + +The `https` service listens on port 443 with the `bk-default` backend +and handles HTTPS traffic using the `cert` certificate for SSL termination. +The HSTS header is set with a 1-year expiry to tell browsers to always use +SSL for the site. + +Rule 10 matches requests with the exact URL path `/.well-known/xxx` and +redirects them to `/certs/`. + +Rule 20 matches requests with URL paths ending in `/mail` or the exact +path `/email/bar` and redirects them to `/postfix/`. + +Global parameters include a maximum connection limit of 4000 and a minimum +TLS version of 1.3. + +```none +set load-balancing haproxy service http description 'Force redirect to HTTPS' +set load-balancing haproxy service http port '80' +set load-balancing haproxy service http redirect-http-to-https + +set load-balancing haproxy service https backend 'bk-default' +set load-balancing haproxy service https description 'listen on 443 port' +set load-balancing haproxy service https mode 'http' +set load-balancing haproxy service https port '443' +set load-balancing haproxy service https ssl certificate 'cert' +set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' + +set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx' +set load-balancing haproxy service https rule 10 set redirect-location '/certs/' +set load-balancing haproxy service https rule 20 url-path end '/mail' +set load-balancing haproxy service https rule 20 url-path exact '/email/bar' +set load-balancing haproxy service https rule 20 set redirect-location '/postfix/' + +set load-balancing haproxy backend bk-default description 'Default backend' +set load-balancing haproxy backend bk-default mode 'http' +set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23' +set load-balancing haproxy backend bk-default server sr01 port '80' + +set load-balancing haproxy global-parameters max-connections '4000' +set load-balancing haproxy global-parameters tls-version-min '1.3' +``` + +### SSL Bridging + +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends it to the backend server via HTTPS. +Use this when encryption is required for both paths but you do not want to +install publicly trusted certificates on each backend server. + +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. + +The `https` service listens on port 443 with backend `bk-bridge-ssl` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. + +The `bk-bridge-ssl` backend connects to `sr01` server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA `cacert` + +```none +set load-balancing haproxy service https backend 'bk-bridge-ssl' +set load-balancing haproxy service https description 'listen on 443 port' +set load-balancing haproxy service https mode 'http' +set load-balancing haproxy service https port '443' +set load-balancing haproxy service https ssl certificate 'cert' + +set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend' +set load-balancing haproxy backend bk-bridge-ssl mode 'http' +set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert' +set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23' +set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443' +``` + +### Balancing with HTTP health checks + +This configuration enables HTTP health checks for backend servers. + +```none +set load-balancing haproxy service my-tcp-api backend 'bk-01' +set load-balancing haproxy service my-tcp-api mode 'tcp' +set load-balancing haproxy service my-tcp-api port '8888' + +set load-balancing haproxy backend bk-01 balance 'round-robin' +set load-balancing haproxy backend bk-01 mode 'tcp' + +set load-balancing haproxy backend bk-01 http-check method 'get' +set load-balancing haproxy backend bk-01 http-check uri '/health' +set load-balancing haproxy backend bk-01 http-check expect 'status 200' + +set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing haproxy backend bk-01 server srv01 port '8881' +set load-balancing haproxy backend bk-01 server srv01 check +set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing haproxy backend bk-01 server srv02 port '8882' +set load-balancing haproxy backend bk-01 server srv02 check port '8892' +``` diff --git a/docs/configuration/loadbalancing/index.md b/docs/configuration/loadbalancing/index.md new file mode 100644 index 00000000..3241edb7 --- /dev/null +++ b/docs/configuration/loadbalancing/index.md @@ -0,0 +1,15 @@ +--- +lastproofread: '2026-04-06' +--- + +(load-balancing)= + +# Load-balancing + +```{toctree} +:includehidden: true +:maxdepth: 1 + +wan +haproxy +``` diff --git a/docs/configuration/loadbalancing/wan.md b/docs/configuration/loadbalancing/wan.md new file mode 100644 index 00000000..a19bbfae --- /dev/null +++ b/docs/configuration/loadbalancing/wan.md @@ -0,0 +1,306 @@ +--- +lastproofread: '2026-04-06' +--- + +# WAN load balancing + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +The load balancer distributes outbound traffic across two or more +interfaces. If a path fails, the load balancer balances traffic across the +remaining healthy paths. When a path recovers, it is automatically added back +to the routing table. The load balancer adds routes for each path and +distributes traffic based on 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). + +The following examples uses two DHCP WAN interfaces and one LAN (`eth2`): + +```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} +Do not use WAN load balancing with dynamic routing protocols. This +feature creates customized routing tables and firewall rules that are +incompatible with routing protocols. +::: + +## Load balancing rules + +You define interfaces, their weight, and the traffic type to balance in +numbered rule sets. The load balancer executes rules in numerical order +against outgoing packets. When a packet matches a rule, it is sent through the +specified interface. Packets that do not match any rule use the system routing +table. You cannot change rule numbers. + +Create a load balancing rule, it can be a number between 1 and 9999: + +```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 + +By default, the load balancer distributes outbound +traffic randomly across available interfaces. You can assign weights to +interfaces to influence the distribution. If `eth0` has more bandwidth +than `eth1`, you can assign a higher weight to `eth0` to send more +traffic through it: + +```none +set load-balancing wan rule 1 interface eth0 weight 2 +set load-balancing wan rule 1 interface eth1 weight 1 +``` + +In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives +33% of traffic. + +### Rate limit + +Set a packet rate limit for a rule to apply it to traffic above or below a +specified threshold. To configure rate limiting, use: + +```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 + +The load balancer balances outgoing traffic by flow. A connection tracking +table tracks flows by source address, destination address, and port. Each +flow is assigned to an interface based on the balancing rules, and subsequent +packets use the same interface. This ensures packets arrive in order when links +have different speeds. + +Packet-based balancing can improve balance across interfaces when packet +order is not critical. Enable per-packet balancing for a rule with: + +```none +set load-balancing wan rule <rule> per-packet-balancing +``` + + +### Exclude traffic + +To exclude traffic from load balancing, traffic matching an exclude rule +bypasses load balancing and uses the system routing table instead: + +```none +set load-balancing wan rule <rule> exclude +``` + + +## Health checks + +The load balancer periodically checks the health of interfaces and paths by +sending ICMP packets (ping) to remote destinations, performing TTL tests, or +executing a user-defined script. If an interface fails the health check, the +load balancer removes it from its interface pool. +To enable health checking for an interface: + +```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 the nexthop on the path to the destination. You can set +`ipv4-address` to `dhcp`. + +```none +set load-balancing wan interface-health <interface> nexthop <ipv4-address> +``` + +Set the number of health check failures before the load balancer marks an +interface as unavailable (range 1-10, default 1). Or set the number of +successful health checks before adding an interface back to the pool +(range 1-10, default 1). + +```none +set load-balancing wan interface-health <interface> failure-count <number> +set load-balancing wan interface-health <interface> success-count <number> +``` + +Configure each health check in its own test. Tests are numbered and processed +in numeric order. You can define multiple tests for multi-target health +checking: + +```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 receive ICMP packets. The address can be an IPv4 + address or hostname. +- `test-script`: A user-defined script must return 0 to succeed and + non-zero to fail. Scripts reside in `/config/scripts`. For other locations, + provide the full path. +- `ttl-limit`: For the UDP TTL limit test, specify the hop count limit. + The limit must be shorter than the path length. The test succeeds when an + ICMP time-expired message is returned. Default `1`. +- `type`: Specify the test type: `ping`, `ttl`, or a user-defined + script. + +## Source NAT rules + +By default, interfaces in a load balancing pool replace the source IP of +each outgoing packet with their own address to ensure replies arrive on the +same interface. The load balancer handles this through automatically generated +Source NAT (SNAT) rules applied only to balanced traffic. To disable the +automatic generation of SNAT rules when this behavior is not desired, use: + +```none +set load-balancing wan disable-source-nat +``` + + +## Sticky connections + +Inbound connections to a WAN interface can be improperly handled when +replies are sent back to the client. + +```{image} /_static/images/sticky-connections.webp +:align: center +:width: 80% +``` + +When responding to an incoming packet, you may want to ensure the response +leaves from the same interface as the incoming packet. Enable sticky +connections in the load balancer to do this: + +```none +set load-balancing wan sticky-connections inbound +``` + + +## Failover + +In failover mode, one interface is primary and other interfaces are +secondary or spare. The load balancer uses only the primary interface. If it +fails, a secondary interface from the available pool takes over. The load +balancer selects the primary interface based on its weight and health. Other +interfaces become secondary. Secondary interfaces are chosen based on their +weight and health. You can also select interface roles based on rule order by +including interfaces in balancing rules and ordering those rules accordingly. +To enable failover mode, create a failover rule: + +```none +set load-balancing wan rule <number> failover +``` + +Existing sessions do not automatically fail over to a new path. Flush the +session table on each connection state change to enable failover: + +```none +set load-balancing wan flush-connections +``` + +:::{warning} +Flushing the session table causes other connections to revert from +flow-based to packet-based balancing until each flow is reestablished. +::: + +## Script execution + +Run a script when an interface state changes. Scripts run from the +`/config/scripts` directory. To use a script in another location, +specify the full path: + +```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: VyOS becomes unresponsive if the +script does not return. +::: + +## Handling and monitoring + +The following command shows WAN load balancer information including test +types and targets. The character at the start of each line indicates the test +state: +- `+` successful. +- `-` failed. +- A blank indicates that no test has been carried out. + +```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: + +```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 + +```none +restart wan-load-balance +``` |