bfdd: add documentation

Add BFD daemon documentation:
* commands;
* man page;
* manual / description;

Signed-off-by: Rafael Zalamena <rzalamena@opensourcerouting.org>

doc/Makefile.am

@@ -86,6 +86,10 @@ if SHARPD
 man_MANS += $(MANPAGE_BUILDDIR)/sharpd.8
 endif
 
+if BFDD
+man_MANS += $(MANPAGE_BUILDDIR)/bfdd.8
+endif
+
 # Automake is particular about manpages. It is aware of them and has some
 # special facilities for handling them, but it assumes that manpages are always
 # given in groff source and so these facilities are limited to simply
@@ -154,6 +158,8 @@ EXTRA_DIST = frr-sphinx.mk \
 	manpages/vtysh.rst \
 	manpages/watchfrr.rst \
 	manpages/zebra.rst \
+	manpages/bfdd.rst \
+	manpages/bfd-options.rst \
 	developer/bgpd.rst \
 	developer/bgp-typecodes.rst \
 	developer/building-frr-on-alpine.rst \
@@ -226,6 +232,7 @@ EXTRA_DIST = frr-sphinx.mk \
 	user/vnc.rst \
 	user/vtysh.rst \
 	user/zebra.rst \
+	user/bfd.rst \
 	mpls/ChangeLog.opaque.txt \
 	mpls/ospfd.conf \
 	mpls/cli_summary.txt \

doc/manpages/bfd-options.rst

@@ -0,0 +1,10 @@
+BFD SOCKET
+----------
+
+The following option controls the BFD daemon control socket location.
+
+.. option:: --bfdctl bfd-control-socket
+
+   Opens the BFD daemon control socket located at the pointed location.
+
+   (default: |INSTALL_PREFIX_STATE|/bfdd.sock)

doc/manpages/bfdd.rst

@@ -0,0 +1,40 @@
+****
+BFDD
+****
+
+.. include:: defines.rst
+.. |DAEMON| replace:: bfdd
+
+SYNOPSIS
+========
+|DAEMON| |synopsis-options-hv|
+
+|DAEMON| |synopsis-options|
+
+DESCRIPTION
+===========
+|DAEMON| is a communication failure detection component that works with
+the FRRouting routing engine.
+
+OPTIONS
+=======
+OPTIONS available for the |DAEMON| command:
+
+.. include:: common-options.rst
+.. include:: bfd-options.rst
+
+FILES
+=====
+
+|INSTALL_PREFIX_SBIN|/|DAEMON|
+   The default location of the |DAEMON| binary.
+
+|INSTALL_PREFIX_ETC|/|DAEMON|.conf
+   The default location of the |DAEMON| config file.
+
+$(PWD)/|DAEMON|.log
+   If the |DAEMON| process is configured to output logs to a file, then you
+   will find this file in the directory where you started |DAEMON|.
+
+.. include:: epilogue.rst
+

doc/manpages/common-options.rst

@@ -123,6 +123,7 @@ These following options control the daemon's VTY (interactive command line) inte
       ldpd            2612
       eigrpd          2613
       pbrd            2615
+      bfdd            2616
 
    Port 2607 is used for ospfd's Opaque LSA API, while port 2600 is used for the (insecure) TCP-ZEBRA interface.
 

doc/manpages/conf.py

@@ -331,6 +331,7 @@
     ('watchfrr', 'watchfrr', 'a program to monitor the status of FRRouting daemons', [], 8),
     ('vtysh', 'vtysh', 'an integrated shell for FRRouting.', [], 1),
     ('frr', 'frr', 'a systemd interaction script', [], 1),
+    ('bfdd', 'bfdd', fwfrr.format("a bfd"), [], 8),
 ]
 
 # -- Options for Texinfo output -------------------------------------------

doc/user/bfd.rst

@@ -0,0 +1,302 @@
+.. _bfd:
+
+**********************************
+Bidirectional Forwarding Detection
+**********************************
+
+:abbr:`BFD (Bidirectional Forwarding Detection)` stands for
+Bidirectional Forwarding Detection and it is described and extended by
+the following RFCs:
+
+* :rfc:`5880`
+* :rfc:`5881`
+* :rfc:`5883`
+
+Currently, there are two implementations of the BFD commands in FRR:
+
+* :abbr:`PTM (Prescriptive Topology Manager)`: an external daemon which
+  implements BFD;
+* ``bfdd``: a BFD implementation that is able to talk with remote peers;
+
+This document will focus on the later implementation: *bfdd*.
+
+
+.. _bfd-starting:
+
+Starting BFD
+============
+
+*bfdd* default configuration file is :file:`bfdd.conf`. *bfdd* searches
+the current directory first then |INSTALL_PREFIX_ETC|/bfdd.conf. All of
+*bfdd*'s command must be configured in :file:`bfdd.conf`.
+
+*bfdd* specific invocation options are described below. Common options
+may also be specified (:ref:`common-invocation-options`).
+
+.. program:: bfdd
+
+.. option:: --bfdctl <unix-socket>
+
+   Set the BFD daemon control socket location. If using a non-default
+   socket location.
+
+      /usr/lib/frr/bfdd --bfdctl /tmp/bfdd.sock
+
+
+   The default UNIX socket location is:
+
+      #define BFDD_CONTROL_SOCKET "|INSTALL_PREFIX_STATE|/bfdd.sock"
+
+
+.. _bfd-commands:
+
+BFDd Commands
+=============
+
+.. index:: bfd
+.. clicmd:: bfd
+
+   Opens the BFD daemon configuration node.
+
+.. index:: peer <A.B.C.D|X:X::X:X> [{multihop|local-address <A.B.C.D|X:X::X:X>|interface IFNAME|vrf NAME}]
+.. clicmd:: peer <A.B.C.D|X:X::X:X> [{multihop|local-address <A.B.C.D|X:X::X:X>|interface IFNAME|vrf NAME}]
+
+   Creates and configures a new BFD peer to listen and talk to.
+
+   `multihop` tells the BFD daemon that we should expect packets with
+   TTL less than 254 (because it will take more than one hop) and to
+   listen on the multihop port (4784). When using multi-hop mode
+   `echo-mode` will not work (see :rfc:`5883` section 3).
+
+   `local-address` provides a local address that we should bind our
+   peer listener to and the address we should use to send the packets.
+   This option is mandatory for IPv6.
+
+   `interface` selects which interface we should use. This option
+   conflicts with `vrf`.
+
+   `vrf` selects which domain we want to use.
+
+.. index:: no peer <A.B.C.D|X:X::X:X>$peer [{multihop|local-address <A.B.C.D|X:X::X:X>$local|interface IFNAME$ifname|vrf NAME$vrfname}]
+.. clicmd:: no peer <A.B.C.D|X:X::X:X>$peer [{multihop|local-address <A.B.C.D|X:X::X:X>$local|interface IFNAME$ifname|vrf NAME$vrfname}]
+
+    Stops and removes the selected peer.
+
+.. index:: show bfd peers [json]
+.. clicmd:: show bfd peers [json]
+
+    Show all configured BFD peers information and current status.
+
+.. index:: show bfd peer <WORD$label|<A.B.C.D|X:X::X:X>$peer [{multihop|local-address <A.B.C.D|X:X::X:X>$local|interface IFNAME$ifname|vrf NAME$vrfname}]> [json]
+.. clicmd:: show bfd peer <WORD$label|<A.B.C.D|X:X::X:X>$peer [{multihop|local-address <A.B.C.D|X:X::X:X>$local|interface IFNAME$ifname|vrf NAME$vrfname}]> [json]
+
+    Show status for a specific BFD peer.
+
+
+.. _bfd-peer-config:
+
+Peer Configurations
+-------------------
+
+.. index:: detect-multiplier (2-255)
+.. clicmd:: detect-multiplier (2-255)
+
+   Configures the detection multiplier to determine packet loss. The
+   remote transmission interval will be multiplied by this value to
+   determine the connection loss detection timer. The default value is
+   3.
+
+   Example: when the local system has `detect-multiplier 3` and  the
+   remote system has `transmission interval 300`, the local system will
+   detect failures only after 900 milliseconds without receiving
+   packets.
+
+.. index:: receive-interval (10-60000)
+.. clicmd:: receive-interval (10-60000)
+
+   Configures the minimum interval that this system is capable of
+   receiving control packets. The default value is 300 milliseconds.
+
+.. index:: transmit-interval (10-60000)
+.. clicmd:: transmit-interval (10-60000)
+
+   The minimum transmission interval (less jitter) that this system
+   wants to use to send BFD control packets.
+
+.. index:: echo-interval (10-60000)
+.. clicmd:: echo-interval (10-60000)
+
+   Configures the minimal echo receive transmission interval that this
+   system is capable of handling.
+
+.. index:: [no] echo-mode
+.. clicmd:: [no] echo-mode
+
+   Enables or disables the echo transmission mode. This mode is disabled
+   by default.
+
+   It is recommended that the transmission interval of control packets
+   to be increased after enabling echo-mode to reduce bandwidth usage.
+   For example: `transmission-interval 2000`.
+
+   Echo mode is not supported on multi-hop setups (see :rfc:`5883`
+   section 3).
+
+.. index:: [no] shutdown
+.. clicmd:: [no] shutdown
+
+   Enables or disables the peer. When the peer is disabled an
+   'administrative down' message is sent to the remote peer.
+
+.. index:: label WORD
+.. clicmd:: label WORD
+
+   Labels a peer with the provided word. This word can be referenced
+   later on other daemons to refer to a specific peer.
+
+
+.. _bfd-bgp-peer-config:
+
+BGP BFD Configuration
+---------------------
+
+.. index:: neighbor <A.B.C.D|X:X::X:X|WORD> bfd
+.. clicmd:: neighbor <A.B.C.D|X:X::X:X|WORD> bfd
+
+   Listen for BFD events registered on the same target as this BGP
+   neighbor. When BFD peer goes down it immediately asks BGP to shutdown
+   the connection with its neighbor and, when it goes back up, notify
+   BGP to try to connect to it.
+
+.. index:: no neighbor <A.B.C.D|X:X::X:X|WORD> bfd
+.. clicmd:: no neighbor <A.B.C.D|X:X::X:X|WORD> bfd
+
+   Removes any notification registration for this neighbor.
+
+
+.. _bfd-configuration:
+
+Configuration
+=============
+
+Before applying ``bfdd`` rules to integrated daemons (like BGPd), we must
+create the corresponding peers inside the ``bfd`` configuration node.
+
+Here is an example of BFD configuration:
+
+::
+
+    bfd
+     peer 192.168.0.1
+       label home-peer
+       no shutdown
+     !
+    !
+    router bgp 65530
+     neighbor 192.168.0.1 remote-as 65531
+     neighbor 192.168.0.1 bfd
+     neighbor 192.168.0.2 remote-as 65530
+     neighbor 192.168.0.2 bfd
+     neighbor 192.168.0.3 remote-as 65532
+     neighbor 192.168.0.3 bfd
+    !
+
+Peers can be identified by its address (use ``multihop`` when you need
+to specify a multi hop peer) or can be specified manually by a label.
+
+Here are the available peer configurations:
+
+::
+
+   bfd
+
+    ! configure a peer on an specific interface
+    peer 192.168.0.1 interface eth0
+     no shutdown
+    !
+
+    ! configure a multihop peer
+    peer 192.168.0.2 multihop local-address 192.168.0.3
+      shutdown
+    !
+
+    ! configure a peer in a different vrf
+    peer 192.168.0.3 vrf foo
+     shutdown
+    !
+
+    ! configure a peer with every option possible
+    peer 192.168.0.4
+     label peer-label
+     detect-multiplier 50
+     receive-interval 60000
+     transmit-interval 3000
+     shutdown
+    !
+
+    ! remove a peer
+    no peer 192.168.0.3 vrf foo
+
+
+.. _bfd-status:
+
+Status
+======
+
+You can inspect the current BFD peer status with the following commands:
+
+::
+
+   frr# show bfd peers
+   BFD Peers:
+           peer 192.168.0.1
+                   ID: 1
+                   Remote ID: 1
+                   Status: up
+                   Uptime: 1 minute(s), 51 second(s)
+                   Diagnostics: ok
+                   Remote diagnostics: ok
+                   Local timers:
+                           Receive interval: 300ms
+                           Transmission interval: 300ms
+                           Echo transmission interval: disabled
+                   Remote timers:
+                           Receive interval: 300ms
+                           Transmission interval: 300ms
+                           Echo transmission interval: 50ms
+
+           peer 192.168.1.1
+                   label: router3-peer
+                   ID: 2
+                   Remote ID: 2
+                   Status: up
+                   Uptime: 1 minute(s), 53 second(s)
+                   Diagnostics: ok
+                   Remote diagnostics: ok
+                   Local timers:
+                           Receive interval: 300ms
+                           Transmission interval: 300ms
+                           Echo transmission interval: disabled
+                   Remote timers:
+                           Receive interval: 300ms
+                           Transmission interval: 300ms
+                           Echo transmission interval: 50ms
+
+   frr# show bfd peer 192.168.1.1
+   BFD Peer:
+               peer 192.168.1.1
+                   label: router3-peer
+                   ID: 2
+                   Remote ID: 2
+                   Status: up
+                   Uptime: 3 minute(s), 4 second(s)
+                   Diagnostics: ok
+                   Remote diagnostics: ok
+                   Local timers:
+                           Receive interval: 300ms
+                           Transmission interval: 300ms
+                           Echo transmission interval: disabled
+                   Remote timers:
+                           Receive interval: 300ms
+                           Transmission interval: 300ms
+                           Echo transmission interval: 50ms