Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)

* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism

Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta's (not current's).

Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
  Sphinx builds, restore after; writes _build/_swap_state.json and
  _build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
  trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
  loader; _prefer_webp builder hook so html prefers webp over png

Content:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
  alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
  (already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
  PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
  default, revert a page by removing its stem from _swap.txt

🤖 Generated by [robots](https://vyos.io)

* feat(conf): copy .md sources into HTML output for plain-text serving

Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.

🤖 Generated by [robots](https://vyos.io)

* docs: address review feedback (backport from PR #1857)

Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.

🤖 Generated by [robots](https://vyos.io)

* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857

Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.

- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
  scripts/swap_sources.py --swap before the Sphinx build and --restore
  after. Without this, the swap mechanism ships but never runs on RTD
  builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
  when self.state._renderer is not present. Required for cfgcmd /
  opcmd / cmdincludemd directives to render correctly when included
  from MyST pages (the swap mechanism's whole point). Sagitta-only
  delta on _ext/vyos.py (the path = str(path) line on 224) is
  intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
  swap scripts. The scripts on this branch are byte-identical to
  current's, so the same tests apply. Travels with the branch so CI
  catches per-branch regressions if the scripts ever drift.

🤖 Generated by [robots](https://vyos.io)

* fix(conf): skip md-*.md staging files in _copy_md_sources

Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc

Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

3 files changed, 880 insertions, 0 deletions

diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md
new file mode 100644
index 00000000..5526c11d
--- /dev/null
+++ b/docs/configuration/loadbalancing/md-index.md
@@ -0,0 +1,8 @@
+# Load-balancing
+
+<div class="toctree" maxdepth="1" includehidden="">
+
+wan
+reverse-proxy
+
+</div>
diff --git a/docs/configuration/loadbalancing/md-reverse-proxy.md b/docs/configuration/loadbalancing/md-reverse-proxy.md
new file mode 100644
index 00000000..0e4ebe77
--- /dev/null
+++ b/docs/configuration/loadbalancing/md-reverse-proxy.md
@@ -0,0 +1,552 @@
+# Reverse-proxy
+
+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
+
+<div class="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
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> port
+\<port\>
+
+Create service <span class="title-ref">\<name\></span> to listen on \<port\>
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> mode
+\<tcp|http\>
+
+Configure service <span class="title-ref">\<name\></span> mode TCP or HTTP
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> backend
+\<name\>
+
+Configure service <span class="title-ref">\<name\></span> to use the backend \<name\>
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> ssl
+certificate \<name\>
+
+Set SSL certificate \<name\> for service \<name\>
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\>
+http-response-headers \<header-name\> value \<header-value\>
+
+Set custom HTTP headers to be included in all responses
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> logging facility
+\<facility\> level \<level\>
+
+Specify facility and level for logging.
+For an explanation on `syslog_facilities` and `syslog_severity_level`
+see tables in syslog configuration section.
+
+</div>
+
+#### 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.
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> rule \<rule\>
+domain-name \<name\>
+
+Match domain name
+
+</div>
+
+<div class="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
+
+</div>
+
+<div class="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
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> rule \<rule\>
+set backend \<name\>
+
+Assign a specific backend to a rule
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy service \<name\> rule \<rule\>
+redirect-location \<url\>
+
+Redirect URL to a new location
+
+</div>
+
+### Backend
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> balance
+\<balance\>
+
+Load-balancing algorithms to be used for distributed requests among the
+available 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 to the server with the fewest
+  active connections
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> mode
+\<mode\>
+
+Configure backend <span class="title-ref">\<name\></span> mode TCP or HTTP
+
+</div>
+
+<div class="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
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> server
+\<name\> port \<port\>
+
+Set the address of the backend port
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> server
+\<name\> check
+
+Active health check backend server
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> server
+\<name\> send-proxy
+
+Send a Proxy Protocol version 1 header (text format)
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> server
+\<name\> send-proxy-v2
+
+Send a Proxy Protocol version 2 header (binary format)
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> ssl
+ca-certificate \<ca-certificate\>
+
+Configure requests to the backend server to use SSL encryption and
+authenticate backend against \<ca-certificate\>
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> ssl no-verify
+
+Configure requests to the backend server to use SSL encryption without
+validating server certificate
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\>
+http-response-headers \<header-name\> value \<header-value\>
+
+Set custom HTTP headers to be included in all responses using the backend
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> logging facility
+\<facility\> level \<level\>
+
+Specify facility and level for logging.
+For an explanation on `syslog_facilities` and `syslog_severity_level`
+see tables in syslog configuration section.
+
+</div>
+
+### Global
+
+Global parameters
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy global-parameters max-connections
+\<num\>
+
+Limit maximum number of connections
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy global-parameters ssl-bind-ciphers
+\<ciphers\>
+
+Limit allowed cipher algorithms used during SSL/TLS handshake
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy global-parameters tls-version-min
+\<version\>
+
+Specify the minimum required TLS version 1.2 or 1.3
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy global-parameters logging
+facility \<facility\> level \<level\>
+
+Specify facility and level for logging.
+For an explanation on `syslog_facilities` and `syslog_severity_level`
+see tables in syslog configuration section.
+
+</div>
+
+## Health checks
+
+### HTTP checks
+
+For web application providing information about their state HTTP health
+checks can be used to determine their availability.
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> http-check
+
+Enables HTTP health checks using OPTION HTTP requests against '/' and
+expecting a successful response code in the 200-399 range.
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> http-check
+method \<method\>
+
+Sets the HTTP method to be used, can be either: option, get, post, put
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> http-check
+uri \<path\>
+
+Sets the endpoint to be used for health checks
+
+</div>
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> http-check
+expect \<condition\>
+
+Sets the expected result condition for considering a server healthy.
+
+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 <span class="title-ref">success</span> in the response body
+
+</div>
+
+### TCP checks
+
+Health checks can also be configured for TCP mode backends. You can configure
+protocol aware checks for a range of Layer 7 protocols:
+
+<div class="cfgcmd">
+
+set load-balancing reverse-proxy backend \<name\> health-check \<protocol\>
+
+Available health check protocols:  
+- `ldap` LDAP protocol check.
+- `redis` Redis protocol check.
+- `mysql` MySQL protocol check.
+- `pgsql` PostgreSQL protocol check.
+- `smtp` SMTP protocol check.
+
+</div>
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+If you specify a server to be checked but do not configure a
+protocol, a basic TCP health check will be attempted. A server shall be
+deemed online if it responses to a connection attempt with a valid
+`SYN/ACK` packet.
+
+</div>
+
+## 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:
+
+``` 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.
+
+``` 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`
+
+``` 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 terminates SSL on the router.
+
+The `http` service is listens 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.
+HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site.
+
+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.
+
+``` 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 http-response-headers Strict-Transport-Security value 'max-age=31536000'
+
+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'
+```
+
+### SSL Bridging
+
+The following configuration terminates incoming HTTPS traffic on the router,
+then re-encrypts the traffic and sends to the backend server via HTTPS.
+This is useful if encryption is required for both legs, 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 reverse-proxy service https backend 'bk-bridge-ssl'
+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 backend bk-bridge-ssl description 'SSL backend'
+set load-balancing reverse-proxy backend bk-bridge-ssl mode 'http'
+set load-balancing reverse-proxy backend bk-bridge-ssl ssl ca-certificate 'cacert'
+set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23'
+set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443'
+```
+
+### Balancing with HTTP health checks
+
+This configuration enables HTTP health checks on backend servers.
+
+``` 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 http-check method 'get'
+set load-balancing reverse-proxy backend bk-01 http-check uri '/health'
+set load-balancing reverse-proxy backend bk-01 http-check expect 'status 200'
+
+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 srv01 check
+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'
+set load-balancing reverse-proxy backend bk-01 server srv02 check
+```
diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md
new file mode 100644
index 00000000..f82c7e4b
--- /dev/null
+++ b/docs/configuration/loadbalancing/md-wan.md
@@ -0,0 +1,320 @@
+lastproofread  
+2023-01-27
+
+# 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):
+
+``` 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
+```
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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.
+
+</div>
+
+## 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:
+
+``` 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.
+
+``` 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:
+
+``` 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:
+
+``` 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:
+
+``` 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:
+
+``` 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`
+
+``` 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.
+
+``` 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:
+
+``` 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:
+
+``` 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.
+
+<img src="/_static/images/sticky-connections.webp" class="align-center" style="width:80.0%" alt="image" />
+
+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:
+
+``` 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:
+
+``` 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:
+
+``` none
+set load-balancing wan flush-connections
+```
+
+<div class="warning">
+
+<div class="title">
+
+Warning
+
+</div>
+
+Flushing the session table will cause other connections to fall back from
+flow-based to packet-based balancing until each flow is reestablished.
+
+</div>
+
+## 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:
+
+``` 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
+
+<div class="warning">
+
+<div class="title">
+
+Warning
+
+</div>
+
+Blocking call with no timeout. System will become unresponsive if script
+does not return!
+
+</div>
+
+## 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
+
+``` 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
+```