docs: Update BFD page to VyOS 1.5 standards (#2056)

* docs: Update BFD page to VyOS 1.5 standards

* Update bfd.md

* Remove mentions of security from the minimum-ttl section

---------

Co-authored-by: Daniil Baturin <daniil@baturin.org>

1 files changed, 315 insertions, 82 deletions

diff --git a/docs/configuration/protocols/bfd.md b/docs/configuration/protocols/bfd.md
index 13623e03..656d67f8 100644
--- a/docs/configuration/protocols/bfd.md
+++ b/docs/configuration/protocols/bfd.md
@@ -1,205 +1,438 @@
 ---
-lastproofread: '2023-01-27'
+myst:
+  html_meta:
+    description: |
+      Bidirectional Forwarding Detection (BFD) is a network protocol that
+      detects communication failures between two connected routing devices
+      in milliseconds.
+    keywords: bfd, bidirectional forwarding detection, bgp, ospf, isis,
+      multihop, echo-mode
 ---
 
-```{include} /_include/need_improvement.txt
-```
-
 (routing-bfd)=
 
 # BFD
 
-{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by
-the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`.
+{abbr}`BFD (Bidirectional Forwarding Detection)` is a network protocol that
+detects communication failures between two connected routing devices in mere
+milliseconds — far faster than traditional routing protocols.
+BFD does not route traffic itself. Instead, it provides rapid failure detection
+for other protocols, such as {abbr}`BGP (Border Gateway Protocol)`,
+{abbr}`OSPF (Open Shortest Path First)`, and static routes.
 
-In the age of very fast networks, a second of unreachability may equal millions of lost packets.
-The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast.
+BFD is described and extended by the following RFCs: {rfc}`5880`, {rfc}`5881`
+and {rfc}`5883`.
 
-BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive.
+**How BFD works**
 
-This allows avoiding the timers defined in BGP and OSPF protocol to expires.
+BFD establishes a session between two peers and exchanges rapid
+{abbr}`UDP (User Datagram Protocol)` control packets at a negotiated interval
+(e.g., 300 ms between consecutive packets). If a peer doesn't receive these
+packets within the detection time (the negotiated interval multiplied by a
+detection multiplier), BFD assumes a connection failure and notifies the
+routing protocols.
 
-## Configure BFD
+## Configuration
 
 ```{cfgcmd} set protocols bfd peer \<address\>
 
-Set BFD peer IPv4 address or IPv6 address
+**Configure the IPv4 or IPv6 address of the BFD peer.**
+
+You can configure multiple BFD peers by specifying a different IP address
+for each neighbor you want to monitor.
+```
+
+```{note}
+For IPv6 peers, you must configure a source IP address or interface.
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33
 ```
 
 ```{cfgcmd} set protocols bfd peer \<address\> echo-mode
 
-Enables the echo transmission mode
+**Enable BFD echo transmission mode for the peer at the specified IP
+address.**
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33 echo-mode
 ```
 
 ```{cfgcmd} set protocols bfd peer \<address\> multihop
 
-Allow this BFD peer to not be directly connected
+**Configure the peer at the specified IP address as a multi-hop neighbor.**
+```
+
+```{note}
+For BFD multi-hop peers, you must configure a local source IP address.
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33 multihop
+set protocols bfd peer 198.51.100.33 source address 198.51.100.1
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> source address \<address\>
+
+**Configure the source IP address for the BFD session with the peer at the
+specified IP address.**
+```
+
+```{note}
+Configuring a source IP address or interface is mandatory for IPv6 BFD
+peers.
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33 source address 198.51.100.1
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> source interface \<interface\>
+
+**Configure the source interface for the BFD session with the peer at the
+specified IP address.**
+```
+
+```{note}
+Configuring a source IP address or interface is mandatory for IPv6 BFD
+peers.
 ```
 
-```{cfgcmd} set protocols bfd peer \<address\> source [address \<address\> | interface \<interface\>]
+Example:
 
-Bind listener to specific interface/address, mandatory for IPv6
+```none
+set protocols bfd peer 2001:db8::2 source interface eth0
 ```
 
 ```{cfgcmd} set protocols bfd peer \<address\> interval echo-interval \<10-60000\>
 
-The minimal echo receive transmission interval that this system is
-capable of handling
+**Configure the minimum interval, in milliseconds, at which the local system
+can receive echo packets from the peer at the specified IP address.**
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33 interval echo-interval 50
 ```
 
 ```{cfgcmd} set protocols bfd peer \<address\> interval multiplier \<2-255\>
 
-Remote transmission interval will be multiplied by this value
+**Configure the detection multiplier for the peer at the specified IP
+address.**
+
+BFD multiplies the negotiated interval by this value to calculate the
+detection time — the period after which it declares the session down if no
+control packets arrive.
+```
+
+Example:
+
+```none
+set protocols bfd peer 192.0.2.1 interval multiplier 3
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> interval receive \<10-60000\>
+
+**Configure the interval, in milliseconds, at which the local system can
+receive BFD control packets from the peer at the specified IP address.**
 ```
 
-```{cfgcmd} set protocols bfd peer \<address\> interval [receive | transmit] \<10-60000\>
+Example:
 
-Interval in milliseconds
+```none
+set protocols bfd peer 192.0.2.1 interval receive 300
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> interval transmit \<10-60000\>
+
+**Configure the interval, in milliseconds, at which you want the local
+system to transmit BFD control packets to the peer at the specified IP
+address.**
+```
+
+Example:
+
+```none
+set protocols bfd peer 192.0.2.1 interval transmit 300
 ```
 
 ```{cfgcmd} set protocols bfd peer \<address\> shutdown
 
-Disable a BFD peer
+**Disable the BFD session with the peer at the specified IP address.**
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33 shutdown
 ```
 
 ```{cfgcmd} set protocols bfd peer \<address\> minimum-ttl \<1-254\>
 
-For multi hop sessions only. Configure the minimum expected TTL for an
-incoming BFD control packet.
+**Configure the minimum {abbr}`TTL (Time to Live)` value that incoming BFD
+control packets must have to be accepted from the peer at the specified IP
+address.**
+
+BFD discards any packet whose TTL is below this threshold.
+```
+
+```{note}
+This setting applies only to multi-hop sessions.
+```
+
+Example:
+
+```none
+set protocols bfd peer 192.0.2.1 minimum-ttl 250
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> passive
+
+**Configure the BFD session with the peer at the specified IP address to
+operate in passive mode.**
+
+In passive mode, the local system does not initiate the BFD session.
+Instead, it waits to receive the first BFD control packet from the remote
+peer.
+```
+
+```{note}
+At least one of the two peers must remain in active mode for the session
+to establish. If both peers are passive, neither will initiate, and the
+session never establishes.
+```
+
+Example:
+
+```none
+set protocols bfd peer 198.51.100.33 passive
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> profile \<profile\>
 
-This feature serves the purpose of thightening the packet validation
-requirements to avoid receiving BFD control packets from other sessions.
+**Apply settings from a designated BFD profile to the peer at the specified
+IP address.**
+```
+
+Example:
+
+```none
+set protocols bfd peer 192.0.2.1 profile datacenter-fast
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> vrf \<vrf\>
+
+**Bind the BFD session with the peer at the specified IP address to a
+specific {abbr}`VRF (Virtual Routing and Forwarding)` instance.**
+```
+
+Example:
+
+```none
+set protocols bfd peer 192.0.2.1 vrf customer-a
 ```
 
 ### Enable BFD in BGP
 
 ```{cfgcmd} set protocols bgp neighbor \<neighbor\> bfd
 
-Enable BFD on a single BGP neighbor
+**Enable BFD failure detection for the BGP session with the neighbor at the
+specified IP address.**
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.1 bfd
 ```
 
 ```{cfgcmd} set protocols bgp peer-group \<neighbor\> bfd
 
-Enable BFD on a BGP peer group
+**Enable BFD failure detection for all neighbors in the specified BGP peer
+group.**
+```
+
+Example:
+
+```none
+set protocols bgp peer-group INTERNAL-PEERS bfd
 ```
 
 ### Enable BFD in OSPF
 
 ```{cfgcmd} set protocols ospf interface \<interface\> bfd
 
-   Enable BFD for OSPF on an interface
+**Enable BFD failure detection for OSPF neighbors discovered on the specified
+interface.**
 
+When OSPF forms an adjacency with a neighbor on this interface, it requests
+BFD to establish a session with that neighbor.
+```
+
+Example:
+
+```none
+set protocols ospf interface eth0 bfd
 ```
 
 ```{cfgcmd} set protocols ospfv3 interface \<interface\> bfd
 
-Enable BFD for OSPFv3 on an interface
+**Enable BFD failure detection for OSPFv3 neighbors discovered on the
+specified interface.**
+
+When OSPFv3 forms an adjacency with a neighbor on this interface, it
+requests BFD to establish a session with that neighbor.
 ```
 
-### Enable BFD in ISIS
+Example:
 
-```{cfgcmd} set protocols isis \<name\> interface \<interface\> bfd
+```none
+set protocols ospfv3 interface eth0 bfd
+```
 
-Enable BFD for ISIS on an interface
+### Enable BFD in IS-IS
 
+```{cfgcmd} set protocols isis interface \<interface\> bfd
+
+**Enable BFD failure detection for IS-IS neighbors discovered on the
+specified interface.**
+
+When IS-IS forms an adjacency with a neighbor on this interface, it requests
+BFD to establish a session with that neighbor.
+```
+
+Example:
+
+```none
+set protocols isis interface eth0 bfd
 ```
 
-## Operational Commands
+## Operation
 
 ```{opcmd} show bfd peers
 
-   Show all BFD peers
+**Show all BFD peers.**
+```
 
-   :::{code-block} none
-   BFD Peers:
-        peer 198.51.100.33 vrf default interface eth4.100
+```none
+vyos@vyos:~$ show bfd peers
+BFD Peers:
+        peer 198.51.100.33 vrf default
                 ID: 4182341893
-                Remote ID: 12678929647
+                Remote ID: 3267892964
+                Active mode
                 Status: up
                 Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s)
                 Diagnostics: ok
                 Remote diagnostics: ok
+                Peer Type: configured
+                RTT min/avg/max: 245/267/289 usec
                 Local timers:
+                        Detect-multiplier: 3
                         Receive interval: 300ms
                         Transmission interval: 300ms
-                        Echo transmission interval: 50ms
+                        Echo receive interval: 50ms
+                        Echo transmission interval: disabled
                 Remote timers:
+                        Detect-multiplier: 3
                         Receive interval: 300ms
                         Transmission interval: 300ms
-                        Echo transmission interval: 0ms
+                        Echo receive interval: disabled
 
-        peer 198.51.100.55 vrf default interface eth4.101
-                ID: 4618932327
+        peer 198.51.100.55 multihop local-address 198.51.100.1 vrf default
+                ID: 3618932327
                 Remote ID: 3312345688
+                Active mode
+                Minimum TTL: 254
                 Status: up
                 Uptime: 20 hour(s), 16 minute(s), 19 second(s)
                 Diagnostics: ok
                 Remote diagnostics: ok
+                Peer Type: configured
+                RTT min/avg/max: 1240/1289/1356 usec
                 Local timers:
+                        Detect-multiplier: 3
                         Receive interval: 300ms
                         Transmission interval: 300ms
-                        Echo transmission interval: 50ms
+                        Echo receive interval: 50ms
+                        Echo transmission interval: disabled
                 Remote timers:
-                        Receive interval: 300ms
-                        Transmission interval: 300ms
-                        Echo transmission interval: 0ms
-   :::
+                        Detect-multiplier: 3
+                        Receive interval: 1000ms
+                        Transmission interval: 1000ms
+                        Echo receive interval: disabled
 ```
 
-## BFD Static Route Monitoring
+## BFD static route monitoring
 
+A monitored static route is present in the
+{abbr}`RIB (Routing Information Base)` only when the BFD session is up. If
+the session goes down, the route is removed.
 
-A monitored static route conditions the installation to the RIB on the BFD
-session running state: when BFD session is up the route is installed to RIB,
-but when the BFD session is down it is removed from the RIB.
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\>
 
+**Configure BFD failure detection for a single-hop static route.**
 
-### Configuration
+BFD uses the next-hop IP address as the BFD peer IP address and applies
+settings from the specified BFD profile.
+```
 
-```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\>
+Example:
 
-Configure a static route for \<subnet\> using gateway \<address\>
-and use the gateway address as BFD peer destination address.
+```none
+set protocols static route 10.0.0.0/24 next-hop 192.0.2.1 bfd profile datacenter-fast
 ```
 
-```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\>
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source-address \<address\>
+
+**Configure BFD failure detection for a multi-hop static route.**
 
-Configure a static route for \<subnet\> using gateway \<address\>,
-use source address to identify the peer when is multi-hop session
-and the gateway address as BFD peer destination address.
+BFD uses the next-hop IP address as the BFD peer IP address and the
+multi-hop source IP address as the local source IP for outgoing BFD packets.
 ```
 
-```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\>
+Example:
 
-Configure a static route for \<subnet\> using gateway \<address\>
-and use the gateway address as BFD peer destination address.
+```none
+set protocols static route 10.0.0.0/24 next-hop 198.51.100.33 bfd multi-hop source-address 198.51.100.1
 ```
 
-```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\>
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\>
 
-Configure a static route for \<subnet\> using gateway \<address\>,
-use source address to identify the peer when is multi-hop session
-and the gateway address as BFD peer destination address.
-```
+**Configure BFD failure detection for a single-hop IPv6 static route.**
 
-(bfd-operational-commands)=
+BFD uses the next-hop IPv6 address as the BFD peer IPv6 address and applies
+settings from the specified BFD profile.
+```
 
-## Operational Commands
+Example:
 
-```{opcmd} show bfd static routes
+```none
+set protocols static route6 2001:db8:1::/64 next-hop 2001:db8::1 bfd profile datacenter-fast
+```
 
-Showing BFD monitored static routes
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source-address \<address\>
 
-:::{code-block} none
-Showing BFD monitored static routes:
+**Configure BFD failure detection for a multi-hop IPv6 static route.**
 
-  Next hops:
-    VRF default IPv4 Unicast:
-        10.10.13.3/32 peer 192.168.2.3 (status: installed)
-        172.16.10.3/32 peer 192.168.10.1 (status: uninstalled)
+BFD uses the next-hop IPv6 address as the BFD peer IPv6 address and the
+multi-hop source IPv6 address as the local source IPv6 address for outgoing
+BFD packets.
+```
 
-    VRF default IPv4 Multicast:
+Example:
 
-    VRF default IPv6 Unicast:
-:::
-```
\ No newline at end of file
+```none
+set protocols static route6 2001:db8:1::/64 next-hop 2001:db8:100::33 bfd multi-hop source-address 2001:db8::1
+```