diff options
Diffstat (limited to 'src/vnet/bfd/bfd_doc.rst')
| -rw-r--r-- | src/vnet/bfd/bfd_doc.rst | 512 |
1 files changed, 512 insertions, 0 deletions
diff --git a/src/vnet/bfd/bfd_doc.rst b/src/vnet/bfd/bfd_doc.rst new file mode 100644 index 00000000000..54a53c6fe92 --- /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. |