DOCS: Update Failover page to VyOS 1.5 standards (#1866)

1 files changed, 182 insertions, 77 deletions

diff --git a/docs/configuration/protocols/failover.rst b/docs/configuration/protocols/failover.rst
index 651fc5c3..c479649e 100644
--- a/docs/configuration/protocols/failover.rst
+++ b/docs/configuration/protocols/failover.rst
@@ -1,119 +1,224 @@
+:description: Failover routes are static routes that are installed in the routing
+   table only while a configured health-check target responds. VyOS uses them
+   to switch traffic to a backup path when the primary next hop becomes
+   unreachable, and to restore the primary path automatically once it recovers.
+:keywords: failover, failover route, static route, health check, icmp probe,
+   next hop, route metric
+
 ########
 Failover
 ########
 
-Failover routes are manually configured routes, but they only install
-to the routing table as kernel routes if the health-check target is alive.
-If the target is not alive the route is removed from the routing table
-until the target becomes available.
+Failover routes are manually configured network paths used only while their
+health-check targets are reachable. If the target stops responding, VyOS
+removes the route from the routing table and reinstalls it once the target
+recovers.
 
-***************
-Failover Routes
-***************
+*************
+Configuration
+*************
 
-.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check 
-   target <target-address>
+Use the following commands to configure failover routes for a specific remote
+``<subnet>`` reachable via next-hop ``<address>``.
 
-   Configure next-hop `<address>` and `<target-address>` for an IPv4 static 
-   route. Specify the target
-   IPv4 address for health checking.
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check target <target-address>
 
-.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check 
-   timeout <timeout>
+   **Configure the health check target IP address.**
 
-   Timeout in seconds between health target checks.
+   This is typically a highly available host, either within the destination
+   subnet or on the public internet.
 
-   Range is 1 to 300, default is 10.
+   Example:
 
-.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check 
-   type <protocol>
+   .. code-block:: none
 
-   Defines protocols for checking ARP, ICMP, TCP.
-* ICMP probe sends 2 ICMP request packets with a response timeout of 1 second.
-  If one ICMP response is received, the health check is successful.
-* ARP probe sends 2 ARP requests with a response timeout of 1 second.
-  If one response is received, the health check is successful.
-* TCP probe checks whether the destination port is open.
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8
 
-   Default is ``icmp``.
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check timeout <timeout>
 
-.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check
-   policy <policy>
+   **Configure the timeout interval, in seconds, between target health checks.**
 
-   Policy for checking targets
+   The valid range is 1 to 300 seconds. The default is 10 seconds.
 
-* ``all-available`` all checking target addresses must be available to pass
-  this check
+   Example:
 
-* ``any-available`` any of the checking target addresses must be available
-  to pass this check
+   .. code-block:: none
 
-   Default is ``any-available``.
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2
 
-.. cfgcmd:: set protocols failover route <subnet> next-hop <address> 
-   interface <interface>
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check type <protocol>
 
-   Next-hop interface for the route
+   **Configure the protocol to use for health checks.**
 
-.. cfgcmd:: set protocols failover route <subnet> next-hop <address> 
-   metric <metric>
+   The following protocols are available:
 
-   Route metric
+   * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second
+     response timeout. The health check is successful if at least one response
+     is received.
+   * ``arp``: VyOS sends two ARP requests with a 1-second response timeout.
+     The health check is successful if at least one response is received.
+   * ``tcp``: VyOS verifies whether the destination TCP port is open. The
+     health check is successful if a TCP connection is successfully
+     established with the target port.
 
-   Default 1.
+   The default protocol is ``icmp``.
 
+   .. note::
 
-*******
-Example
-*******
+      When the check type is set to ``tcp``, you must also define the target
+      TCP port.
 
-**One gateway:**
+   Example:
 
-.. code-block:: none
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp
+
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check port <port>
+
+   **Configure the destination TCP port on the health check target.**
+
+   This parameter applies only when the check type is configured as ``tcp``.
+
+   The valid port range is 1 to 65535.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443
+
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check policy <policy>
+
+   **Configure the health check success policy for multiple targets.**
+
+   The following policies are available:
+
+   * ``any-available``: The health check succeeds if at least one of the
+     configured targets responds successfully.
+   * ``all-available``: The health check succeeds only if every configured
+     target responds successfully.
+
+   The default policy is ``any-available``.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available
+
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> interface <interface>
+
+   **Configure the local interface used to reach the next-hop address.**
+
+   This parameter is mandatory.
 
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10'
+   Example:
 
-Show the route
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0
+
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> metric <1-255>
+
+   **Configure the metric (cost) for the failover route.**
+
+   The metric defines the route priority. A lower metric value indicates a
+   more preferred route.
+
+   The default value is 1.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50
+
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> onlink
+
+   Configure the next-hop to be reachable via the assigned interface, even
+   when ``<address>`` is outside any subnet configured on that interface.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink
+
+********
+Examples
+********
+
+Failover route with a single next-hop and ICMP health check
+===========================================================
+
+The following example configures a failover route to ``203.0.113.1/32``
+through next-hop ``192.0.2.1`` on ``eth0``. The next-hop is monitored with
+ICMP probes to ``192.0.2.1`` every 5 seconds, and the route is installed with
+a metric of 10.
 
 .. code-block:: none
 
-  vyos@vyos:~$ show ip route 203.0.113.1
-    Routing entry for 203.0.113.1/32
-    Known via "kernel", distance 0, metric 10, best
-    Last update 00:00:39 ago
-    * 192.0.2.1, via eth0
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10'
 
-**Two gateways and different metrics:**
+Verify the route:
 
 .. code-block:: none
 
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0'
-  set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10'
+   vyos@vyos:~$ show ip route 203.0.113.1
+   Routing entry for 203.0.113.1/32
+     Known via "kernel", distance 0, metric 10, best
+     Last update 00:00:39 ago
+     Flags: Selected
+     Status: Installed
+     * 192.0.2.1, via eth0, weight 1
 
-  set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99'
-  set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5'
-  set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp'
-  set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2'
-  set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20'
+Two failover routes with different metrics
+==========================================
 
-Show the route
+The following example configures two failover routes to ``203.0.113.1/32``,
+each through a different next-hop. The primary next-hop ``192.0.2.1`` is
+reached on ``eth0`` with metric 10, and the backup next-hop ``198.51.100.1``
+is reached on ``eth2`` with metric 20. Both next-hops are monitored with ICMP
+probes every 5 seconds.
+
+While both health checks succeed, the lower-metric route through ``eth0`` is
+preferred. If the primary target stops responding, its route is removed from
+the routing table, and traffic falls over to ``198.51.100.1`` via ``eth2``.
 
 .. code-block:: none
 
-  vyos@vyos:~$ show ip route 203.0.113.1
-  Routing entry for 203.0.113.1/32
-    Known via "kernel", distance 0, metric 10, best
-    Last update 00:08:06 ago
-    * 192.0.2.1, via eth0
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0'
+   set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10'
+
+   set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99'
+   set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5'
+   set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp'
+   set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2'
+   set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20'
+
+Verify routes:
+
+.. code-block:: none
 
-  Routing entry for 203.0.113.1/32
-    Known via "kernel", distance 0, metric 20
-    Last update 00:08:14 ago
-    * 198.51.100.1, via eth2
+   vyos@vyos:~$ show ip route 203.0.113.1
+   Routing entry for 203.0.113.1/32
+     Known via "kernel", distance 0, metric 10, best
+     Last update 00:08:06 ago
+     Flags: Selected
+     Status: Installed
+     * 192.0.2.1, via eth0, weight 1
+
+   Routing entry for 203.0.113.1/32
+     Known via "kernel", distance 0, metric 20
+     Last update 00:08:14 ago
+     Flags: None
+     Status: Installed
+     * 198.51.100.1, via eth2, weight 1
\ No newline at end of file