docs: convert vpp doc md->rst
Type: improvement
Change-Id: If453321785b04f9c16e8cea36fb1910efaeb2c59
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
diff --git a/src/vnet/bfd/bfd_doc.rst b/src/vnet/bfd/bfd_doc.rst
new file mode 100644
index 0000000..54a53c6
--- /dev/null
+++ b/src/vnet/bfd/bfd_doc.rst
@@ -0,0 +1,512 @@
+.. _bfd_doc:
+
+BFD module
+==========
+
+Overview
+--------
+
+Bidirectional Forwarding Detection in VPP currently supports single-hop
+UDP transport based on RFC 5880 and RFC 5881.
+
+Usage
+-----
+
+General usage
+~~~~~~~~~~~~~
+
+BFD sessions are created using APIs only. The following CLIs are
+implemented, which call the APIs to manipulate the BFD:
+
+Show commands:
+^^^^^^^^^^^^^^
+
+ show bfd [keys|sessions|echo-source]
+
+Show the existing keys, sessions or echo-source.
+
+Key manipulation
+^^^^^^^^^^^^^^^^
+
+Create a new key or modify an existing key
+''''''''''''''''''''''''''''''''''''''''''
+
+ bfd key set conf-key-id type <keyed-sha1|meticulous-keyed-sha1>
+ secret
+
+Parameters:
+
+- conf-key-id - local configuration key ID, used to uniquely identify
+ this key
+- type - type of the key
+- secret - shared secret (hex data)
+
+Example:
+
+ bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret
+ 69d685b0d990cdba46872706dc
+
+Notes:
+
+- in-use key cannot be modified
+
+Delete an existing key
+''''''''''''''''''''''
+
+ bfd key del conf-key-id
+
+Parameters:
+
+- conf-key-id - local configuration key ID, used to uniquely identify
+ this key
+
+Example:
+
+ bfd key del conf-key-id 2368880803
+
+Notes:
+
+- in-use key cannot be deleted
+
+Create a new (plain or authenticated) BFD session
+'''''''''''''''''''''''''''''''''''''''''''''''''
+
+ bfd udp session add interface local-addr
+
+ .. raw:: html
+
+ <address>
+
+ peer-addr
+
+ .. raw:: html
+
+ <address>
+
+ desired-min-tx required-min-rx detect-mult [ conf-key-id bfd-key-id ]
+
+Parameters:
+
+- interface - interface to which this session is tied to
+- local-addr - local address (ipv4 or ipv6)
+- peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
+- desired-min-tx - desired minimum tx interval (microseconds)
+- required-min-rx - required minimum rx interval (microseconds)
+- detect-mult - detect multiplier (must be non-zero)
+- conf-key-id - local configuration key ID
+- bfd-key-id - BFD key ID, as carried in BFD control frames
+
+Example:
+
+ bfd udp session add interface pg0 local-addr fd01:1::1 peer-addr
+ fd01:1::2 desired-min-tx 100000 required-min-rx 100000 detect-mult 3
+ conf-key-id 1029559112 bfd-key-id 13
+
+Notes:
+
+- if conf-key-id and bfd-key-id are not specified, session is
+ non-authenticated
+- desired-min-tx controls desired transmission rate of both control
+ frames and echo packets
+
+Modify BFD session
+''''''''''''''''''
+
+ bfd udp session mod interface local-addr
+
+ .. raw:: html
+
+ <address>
+
+ peer-addr
+
+ .. raw:: html
+
+ <address>
+
+ desired-min-tx required-min-rx detect-mult
+
+Parameters:
+
+- interface - interface to which this session is tied to
+- local-addr - local address (ipv4 or ipv6)
+- peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
+- desired-min-tx - desired minimum tx interval (microseconds)
+- required-min-rx - required minimum rx interval (microseconds)
+- detect-mult - detect multiplier (must be non-zero)
+
+Example:
+
+ bfd udp session mod interface pg0 local-addr 172.16.1.1 peer-addr
+ 172.16.1.2 desired-min-tx 300000 required-min-rx 200000 detect-mult
+ 12
+
+Notes:
+
+- desired-min-tx controls desired transmission rate of both control
+ frames and echo packets
+
+Delete an existing BFD session
+''''''''''''''''''''''''''''''
+
+ bfd udp session del interface local-addr
+
+ .. raw:: html
+
+ <address>
+
+ peer-addr
+
+ .. raw:: html
+
+ <address>
+
+Parameters:
+
+- interface - interface to which this session is tied to
+- local-addr - local address (ipv4 or ipv6)
+- peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
+
+Example:
+
+ bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr
+ 172.16.1.2
+
+Set session admin-up or admin-down
+''''''''''''''''''''''''''''''''''
+
+ bfd udp session set-flags interface local-addr
+
+ .. raw:: html
+
+ <address>
+
+ peer-addr
+
+ .. raw:: html
+
+ <address>
+
+ admin <up|down>
+
+Parameters:
+
+- interface - interface to which this session is tied to
+- local-addr - local address (ipv4 or ipv6)
+- peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
+- admin - up/down based on desired action
+
+Example:
+
+ bfd udp session set-flags admin down interface pg0 local-addr
+ 172.16.1.1 peer-addr 172.16.1.2
+
+Activate/change authentication for existing session
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+ bfd udp session auth activate interface local-addr
+
+ .. raw:: html
+
+ <address>
+
+ peer-addr
+
+ .. raw:: html
+
+ <address>
+
+ conf-key-id bfd-key-id [ delayed <yes|no> ]
+
+Parameters:
+
+- interface - interface to which this session is tied to
+- local-addr - local address (ipv4 or ipv6)
+- peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
+- conf-key-id - local configuration key ID
+- bfd-key-id - BFD key ID, as carried in BFD control frames
+- delayed - is yes then this action is delayed until the peer performs
+ the same action
+
+Example:
+
+ bfd udp session auth activate interface pg0 local-addr 172.16.1.1
+ peer-addr 172.16.1.2 conf-key-id 540928695 bfd-key-id 239 delayed yes
+
+Notes:
+
+- see `Delayed option <#delayed-option>`__ for more information
+
+Deactivate authentication for existing session
+''''''''''''''''''''''''''''''''''''''''''''''
+
+ bfd udp session auth deactivate interface local-addr
+
+ .. raw:: html
+
+ <address>
+
+ peer-addr
+
+ .. raw:: html
+
+ <address>
+
+ [ delayed <yes|no> ]
+
+Parameters:
+
+- interface - interface to which this session is tied to
+- local-addr - local address (ipv4 or ipv6)
+- peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
+- delayed - is yes then this action is delayed until the peer performs
+ the same action
+
+Example:
+
+ bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1
+ peer-addr 172.16.1.2
+
+Notes:
+
+- see `Delayed option <#delayed-option>`__ for more information
+
+Set echo-source interface
+'''''''''''''''''''''''''
+
+ bfd udp echo-source set interface
+
+Parameters:
+
+- interface - interface used for getting source address for echo
+ packets
+
+Example:
+
+ bfd udp echo-source set interface loop0
+
+Delete echo-source interface
+''''''''''''''''''''''''''''
+
+ bfd udp echo-source del
+
+Example:
+
+ bfd udp echo-source del
+
+Authentication
+~~~~~~~~~~~~~~
+
+BFD sessions should be authenticated for security purposes. SHA1 and
+meticulous SHA1 authentication is supported by VPP. First,
+authentication keys are configured in VPP and afterwards they can be
+used by sessions.
+
+There are two key IDs in the scope of BFD session:
+
+- configuration key ID is the internal unique key ID inside VPP and is
+ never communicated to any peer, it serves only the purpose of
+ identifying the key
+- BFD key ID is the key ID carried in BFD control frames and is used
+ for verifying authentication
+
+Turning auth on/off
+^^^^^^^^^^^^^^^^^^^
+
+Authentication can be turned on or off at any time. Care must be taken
+however, to either synchronize the authentication manipulation with
+peer’s actions to avoid the session going down.
+
+Delayed option
+''''''''''''''
+
+Delayed option is useful for synchronizing authentication changes with a
+peer. If it’s specified, then authentication change is not performed
+immediately. In this case, VPP continues to transmit packets using the
+old authentication method (unauthenticated or using old sha1 key). If a
+packet is received, which does not pass the current authentication, then
+VPP tries to authenticate it using the new method (which might be none,
+if deactivating authentication) and if it passes, then the new
+authentication method is put in use.
+
+The recommended procedure for enabling/changing/disabling session
+authentication is:
+
+1. perform authentication change on vpp’s side with delayed option set
+ to yes
+2. perform authentication change on peer’s side (without delayed option)
+
+Notes:
+
+- if both peers use delayed option at the same time, the change will
+ never be carried out, since none of the peers will see any packet
+ with the new authentication which could trigger the change
+- remote peer does not need to support or even be aware of this
+ mechanism for it to work properly
+
+Echo function
+~~~~~~~~~~~~~
+
+Echo function is used by VPP whenever a peer declares the willingness to
+support it, echo-source is set and it contains a usable subnet (see
+below). When echo function is switched on, the required min rx interval
+advertised to peer is set to 1 second (or the configured value, if its
+higher).
+
+Echo source address
+^^^^^^^^^^^^^^^^^^^
+
+Because echo packets are only looped back (and not processed in any way)
+by a peer, it’s necessary to set the source address in a way which
+avoids packet drop due to spoofing protection by VPP. Per RFC, the
+source address should not be in the subnet set on the interface over
+which the echo packets are sent. Also, it must not be any VPP-local
+address, otherwise the packet gets dropped on receipt by VPP. The
+solution is to create a loopback interface with a (private) IPv4/IPv6
+subnet assigned as echo-source. The BFD then picks an unused address
+from the subnet by flipping the last bit and uses that as source address
+in the echo packets, thus meeting RFC recommendation while avoiding
+spoofing protection.
+
+Example: if 10.10.10.3/31 is the subnet, then 10.10.10.2 will be used as
+source address in (IPv4) echo packets
+
+Demand mode
+~~~~~~~~~~~
+
+Demand mode is respected by VPP, but not used locally. The only scenario
+when demand mode could make sense currently is when echo is active.
+Because echo packets are inherently insecure against an adversary
+looping them back a poll sequence would be required for slow periodic
+connectivity verification anyway. It’s more efficient to just ask the
+remote peer to send slow periodic control frames without VPP initiating
+periodic poll sequences.
+
+Admin-down
+~~~~~~~~~~
+
+Session may be put admin-down at any time. This immediately causes the
+state to be changed to AdminDown and remain so unless the session is put
+admin-up.
+
+BFD implementation notes
+------------------------
+
+Because BFD can work over different transport layers, the BFD code is
+separated into core BFD functionality - main module implemented in
+bfd_main.c and transport-specific code implemented in bfd_udp.c.
+
+Main module
+~~~~~~~~~~~
+
+Main module is responsible for handling all the BFD functionality
+defined in RFC 5880.
+
+Internal API
+^^^^^^^^^^^^
+
+Internal APIs defined in bfd_main.h are called from transport-specific
+code to create/modify/delete
+
+Packet receipt
+^^^^^^^^^^^^^^
+
+When a packet is received by the transport layer, it is forwarded to
+main module (to main thread) via an RPC call. At this point, the
+authentication has been verified, so the packet is consumed, session
+parameters are updated accordingly and state change (if applicable).
+Based on these, the timeouts are adjusted if required and an event is
+sent to the process node to wake up and recalculate sleep time.
+
+Packet transmit
+^^^^^^^^^^^^^^^
+
+Main module allocates a vlib_buffer_t, creates the required BFD frame
+(control or echo in it), then calls the transport layer to add the
+transport layer. Then a frame containing the buffer to the appropriate
+node is created and enqueued.
+
+Process node
+^^^^^^^^^^^^
+
+Main module implements one process node which is a simple loop. The
+process node gets next timeout from the timer wheel, sleeps until the
+timeout expires and then calls a timeout routine which drives the state
+machine for each session which timed out. The sleep is interrupted
+externally via vlib event, when a session is added or modified in a way
+which might require timer wheel manipulation. In this case the caller
+inserts the necessary timeout to timer wheel and then signals the
+process node to wake up early, handle possible timeouts and recalculate
+the sleep time again.
+
+State machine
+^^^^^^^^^^^^^
+
+Default state of BFD session when created is Down, per RFC 5880. State
+changes to Init, Up or Down based on events like received state from
+peer and timeouts. The session state can be set AdminDown using a binary
+API, which prevents it from going to any other state, until this
+limitation is removed. This state is advertised to peers in slow
+periodic control frames.
+
+For each session, the following timeouts are maintained:
+
+1. tx timeout - used for sending out control frames
+2. rx timeout - used for detecting session timeout
+3. echo tx timeout - used for sending out echo frames
+4. echo rx timeout - used for detecting session timeout based on echo
+
+These timeouts are maintained in cpu clocks and recalculated when
+appropriate (e.g. rx timeout is bumped when a packet is received,
+keeping the session alive). Only the earliest timeout is inserted into
+the timer wheel at a time and timer wheel events are never deleted,
+rather spurious events are ignored. This allows efficient operation,
+like not inserting events into timing wheel for each packet received or
+ignoring left-over events in case a bfd session gets removed and a new
+one is recreated with the same session index.
+
+Authentication keys management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Authentication keys are managed internally in a pool, with each key
+tracking it’s use count. The removal/modification is only allowed if the
+key is not in use.
+
+UDP module
+~~~~~~~~~~
+
+UDP module is responsible for:
+
+1. public APIs/CLIs to configure BFD over UDP.
+2. support code called by main module to encapsulate/decapsulate BFD
+ packets
+
+This module implements two graph nodes - for consuming ipv4 and ipv6
+packets target at BFD ports 3874 and 3875.
+
+.. _packet-receipt-1:
+
+Packet receipt
+^^^^^^^^^^^^^^
+
+BFD packet receipt receipt starts in the bfd udp graph nodes. Since the
+code needs to verify IP/UDP header data, it relies on ip4-local (and
+ip6-local) nodes to store pointers to the appropriate headers. First,
+your discriminator is extracted from BFD packet and used to lookup the
+existing session. In case it’s zero, the pair of IP addresses and
+sw_if_index is used to lookup session. Then, main module is called to
+verify the authentication, if present. Afterwards a check is made if the
+IP/UDP headers are correct. If yes, then an RPC call is made to the main
+thread to consume the packet and take action upon it.
+
+Packet transmission
+^^^^^^^^^^^^^^^^^^^
+
+When process node decides that there is a need to transmit the packet,
+it creates a buffer, fills the BFD frame data in and calls the UDP
+module to add the transport layer. This is a simple operation for the
+control frames consisting of just adding UDP/IP headers based on session
+data. For echo frames, an additional step, looking at the echo-source
+interface and picking and address is performed and if this fails, then
+the packet cannot be transmitted and an error is returned to main
+thread.