From c44032c1ffa9981409de5570a3301e5f05abd027 Mon Sep 17 00:00:00 2001 From: Rafael Zalamena Date: Wed, 27 Jun 2018 14:24:40 -0300 Subject: [PATCH] bfdd: add documentation Add BFD daemon documentation: * commands; * man page; * manual / description; Signed-off-by: Rafael Zalamena --- doc/Makefile.am | 7 + doc/manpages/bfd-options.rst | 10 ++ doc/manpages/bfdd.rst | 40 +++++ doc/manpages/common-options.rst | 1 + doc/manpages/conf.py | 1 + doc/user/bfd.rst | 302 ++++++++++++++++++++++++++++++++ doc/user/index.rst | 1 + doc/user/installation.rst | 4 + doc/user/overview.rst | 8 + doc/user/setup.rst | 3 + 10 files changed, 377 insertions(+) create mode 100644 doc/manpages/bfd-options.rst create mode 100644 doc/manpages/bfdd.rst create mode 100644 doc/user/bfd.rst diff --git a/doc/Makefile.am b/doc/Makefile.am index da8ac3d050..dce1398720 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -90,6 +90,10 @@ if STATICD man_MANS += $(MANPAGE_BUILDDIR)/staticd.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 @@ -159,6 +163,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 \ @@ -234,6 +240,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 \ diff --git a/doc/manpages/bfd-options.rst b/doc/manpages/bfd-options.rst new file mode 100644 index 0000000000..e335ed120b --- /dev/null +++ b/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) diff --git a/doc/manpages/bfdd.rst b/doc/manpages/bfdd.rst new file mode 100644 index 0000000000..1f8b1475f4 --- /dev/null +++ b/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 + diff --git a/doc/manpages/common-options.rst b/doc/manpages/common-options.rst index 1b2eb18dea..1e99010505 100644 --- a/doc/manpages/common-options.rst +++ b/doc/manpages/common-options.rst @@ -124,6 +124,7 @@ These following options control the daemon's VTY (interactive command line) inte eigrpd 2613 pbrd 2615 staticd 2616 + bfdd 2617 Port 2607 is used for ospfd's Opaque LSA API, while port 2600 is used for the (insecure) TCP-ZEBRA interface. diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py index 4d5797f613..e540d236ea 100644 --- a/doc/manpages/conf.py +++ b/doc/manpages/conf.py @@ -332,6 +332,7 @@ man_pages = [ ('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 ------------------------------------------- diff --git a/doc/user/bfd.rst b/doc/user/bfd.rst new file mode 100644 index 0000000000..0e0fd23ece --- /dev/null +++ b/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 + + 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 [{multihop|local-address |interface IFNAME|vrf NAME}] +.. clicmd:: peer [{multihop|local-address |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 $peer [{multihop|local-address $local|interface IFNAME$ifname|vrf NAME$vrfname}] +.. clicmd:: no peer $peer [{multihop|local-address $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 $peer [{multihop|local-address $local|interface IFNAME$ifname|vrf NAME$vrfname}]> [json] +.. clicmd:: show bfd peer $peer [{multihop|local-address $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 bfd +.. clicmd:: neighbor 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 bfd +.. clicmd:: no neighbor 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 diff --git a/doc/user/index.rst b/doc/user/index.rst index 14688e05d8..5818551343 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -39,6 +39,7 @@ Protocols :maxdepth: 2 zebra + bfd bgp babeld ldpd diff --git a/doc/user/installation.rst b/doc/user/installation.rst index 158e2c8595..3da5a6cd30 100644 --- a/doc/user/installation.rst +++ b/doc/user/installation.rst @@ -103,6 +103,10 @@ options from the list below. Do not build bgpd. +.. option:: --disable-bfdd + + Do not build bfdd. + .. option:: --disable-bgp-announce Make *bgpd* which does not make bgp announcements at all. This diff --git a/doc/user/overview.rst b/doc/user/overview.rst index 4886b57594..369f17dcba 100644 --- a/doc/user/overview.rst +++ b/doc/user/overview.rst @@ -245,6 +245,14 @@ FRR implements the following RFCs: - :rfc:`7552` :t:`Updates to LDP for IPv6, R. Asati, C. Pignataro, K. Raza, V. Manral, and R. Papneja. June 2015.` +- :rfc:`5880` + :t:`Bidirectional Forwarding Detection (BFD), D. Katz, D. Ward. June 2010` +- :rfc:`5881` + :t:`Bidirectional Forwarding Detection (BFD) for IPv4 and IPv6 (Single Hop), + D. Katz, D. Ward. June 2010` +- :rfc:`5883` + :t:`Bidirectional Forwarding Detection (BFD) for Multihop Paths, D. Katz, + D. Ward. June 2010` **When SNMP support is enabled, the following RFCs are also supported:** diff --git a/doc/user/setup.rst b/doc/user/setup.rst index e9fd44a347..68ce14982b 100644 --- a/doc/user/setup.rst +++ b/doc/user/setup.rst @@ -31,6 +31,7 @@ systemd. The file initially looks like this: sharpd=no staticd=no pbrd=no + bfdd=no To enable a particular daemon, simply change the corresponding 'no' to 'yes'. Subsequent service restarts should start the daemon. @@ -66,6 +67,7 @@ This file has several parts. Here is an example: sharpd_options=" --daemon -A 127.0.0.1" staticd_options=" --daemon -A 127.0.0.1" pbrd_options=" --daemon -A 127.0.0.1" + bfdd_options=" --daemon -A 127.0.0.1" # The list of daemons to watch is automatically generated by the init script. watchfrr_enable=yes @@ -136,6 +138,7 @@ add the following entries to :file:`/etc/services`. pimd 2611/tcp # PIMd vty ldpd 2612/tcp # LDPd vty eigprd 2613/tcp # EIGRPd vty + bfdd 2617/tcp # bfdd vty If you use a FreeBSD newer than 2.2.8, the above entries are already added to -- 2.39.5