From 45f174aaac69a738a0bf95ac11a1019cbb8e8cc2 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Fri, 1 May 2026 19:04:05 +0200 Subject: DOCS: Update Failover page to VyOS 1.5 standards (#1866) --- docs/configuration/protocols/failover.rst | 259 +++++++++++++++++++++--------- 1 file 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 next-hop
check - target +Use the following commands to configure failover routes for a specific remote +```` reachable via next-hop ``
``. - Configure next-hop `
` and `` for an IPv4 static - route. Specify the target - IPv4 address for health checking. +.. cfgcmd:: set protocols failover route next-hop
check target -.. cfgcmd:: set protocols failover route next-hop
check - 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 next-hop
check - type + .. 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 next-hop
check timeout -.. cfgcmd:: set protocols failover route next-hop
check - 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 next-hop
- interface +.. cfgcmd:: set protocols failover route next-hop
check type - Next-hop interface for the route + **Configure the protocol to use for health checks.** -.. cfgcmd:: set protocols failover route next-hop
- 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 next-hop
check 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 next-hop
check 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 next-hop
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 next-hop
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 next-hop
onlink + + Configure the next-hop to be reachable via the assigned interface, even + when ``
`` 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 -- cgit v1.2.3