9 Bidirectional Forwarding Detection in VPP currently supports single-hop
10 UDP transport based on RFC 5880 and RFC 5881.
18 BFD sessions are created using APIs only. The following CLIs are
19 implemented, which call the APIs to manipulate the BFD:
24 show bfd [keys|sessions|echo-source]
26 Show the existing keys, sessions or echo-source.
31 Create a new key or modify an existing key
32 ''''''''''''''''''''''''''''''''''''''''''
34 bfd key set conf-key-id type <keyed-sha1|meticulous-keyed-sha1>
39 - conf-key-id - local configuration key ID, used to uniquely identify
41 - type - type of the key
42 - secret - shared secret (hex data)
46 bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret
47 69d685b0d990cdba46872706dc
51 - in-use key cannot be modified
53 Delete an existing key
54 ''''''''''''''''''''''
56 bfd key del conf-key-id
60 - conf-key-id - local configuration key ID, used to uniquely identify
65 bfd key del conf-key-id 2368880803
69 - in-use key cannot be deleted
71 Create a new (plain or authenticated) BFD session
72 '''''''''''''''''''''''''''''''''''''''''''''''''
74 bfd udp session add interface local-addr
86 desired-min-tx required-min-rx detect-mult [ conf-key-id bfd-key-id ]
90 - interface - interface to which this session is tied to
91 - local-addr - local address (ipv4 or ipv6)
92 - peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
93 - desired-min-tx - desired minimum tx interval (microseconds)
94 - required-min-rx - required minimum rx interval (microseconds)
95 - detect-mult - detect multiplier (must be non-zero)
96 - conf-key-id - local configuration key ID
97 - bfd-key-id - BFD key ID, as carried in BFD control frames
101 bfd udp session add interface pg0 local-addr fd01:1::1 peer-addr
102 fd01:1::2 desired-min-tx 100000 required-min-rx 100000 detect-mult 3
103 conf-key-id 1029559112 bfd-key-id 13
107 - if conf-key-id and bfd-key-id are not specified, session is
109 - desired-min-tx controls desired transmission rate of both control
110 frames and echo packets
115 bfd udp session mod interface local-addr
127 desired-min-tx required-min-rx detect-mult
131 - interface - interface to which this session is tied to
132 - local-addr - local address (ipv4 or ipv6)
133 - peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
134 - desired-min-tx - desired minimum tx interval (microseconds)
135 - required-min-rx - required minimum rx interval (microseconds)
136 - detect-mult - detect multiplier (must be non-zero)
140 bfd udp session mod interface pg0 local-addr 172.16.1.1 peer-addr
141 172.16.1.2 desired-min-tx 300000 required-min-rx 200000 detect-mult
146 - desired-min-tx controls desired transmission rate of both control
147 frames and echo packets
149 Delete an existing BFD session
150 ''''''''''''''''''''''''''''''
152 bfd udp session del interface local-addr
166 - interface - interface to which this session is tied to
167 - local-addr - local address (ipv4 or ipv6)
168 - peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
172 bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr
175 Set session admin-up or admin-down
176 ''''''''''''''''''''''''''''''''''
178 bfd udp session set-flags interface local-addr
194 - interface - interface to which this session is tied to
195 - local-addr - local address (ipv4 or ipv6)
196 - peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
197 - admin - up/down based on desired action
201 bfd udp session set-flags admin down interface pg0 local-addr
202 172.16.1.1 peer-addr 172.16.1.2
204 Activate/change authentication for existing session
205 '''''''''''''''''''''''''''''''''''''''''''''''''''
207 bfd udp session auth activate interface local-addr
219 conf-key-id bfd-key-id [ delayed <yes|no> ]
223 - interface - interface to which this session is tied to
224 - local-addr - local address (ipv4 or ipv6)
225 - peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
226 - conf-key-id - local configuration key ID
227 - bfd-key-id - BFD key ID, as carried in BFD control frames
228 - delayed - is yes then this action is delayed until the peer performs
233 bfd udp session auth activate interface pg0 local-addr 172.16.1.1
234 peer-addr 172.16.1.2 conf-key-id 540928695 bfd-key-id 239 delayed yes
238 - see `Delayed option <#delayed-option>`__ for more information
240 Deactivate authentication for existing session
241 ''''''''''''''''''''''''''''''''''''''''''''''
243 bfd udp session auth deactivate interface local-addr
259 - interface - interface to which this session is tied to
260 - local-addr - local address (ipv4 or ipv6)
261 - peer-addr - peer address (ipv4 or ipv6, must match local-addr family)
262 - delayed - is yes then this action is delayed until the peer performs
267 bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1
272 - see `Delayed option <#delayed-option>`__ for more information
274 Set echo-source interface
275 '''''''''''''''''''''''''
277 bfd udp echo-source set interface
281 - interface - interface used for getting source address for echo
286 bfd udp echo-source set interface loop0
288 Delete echo-source interface
289 ''''''''''''''''''''''''''''
291 bfd udp echo-source del
295 bfd udp echo-source del
300 BFD sessions should be authenticated for security purposes. SHA1 and
301 meticulous SHA1 authentication is supported by VPP. First,
302 authentication keys are configured in VPP and afterwards they can be
305 There are two key IDs in the scope of BFD session:
307 - configuration key ID is the internal unique key ID inside VPP and is
308 never communicated to any peer, it serves only the purpose of
310 - BFD key ID is the key ID carried in BFD control frames and is used
311 for verifying authentication
316 Authentication can be turned on or off at any time. Care must be taken
317 however, to either synchronize the authentication manipulation with
318 peer’s actions to avoid the session going down.
323 Delayed option is useful for synchronizing authentication changes with a
324 peer. If it’s specified, then authentication change is not performed
325 immediately. In this case, VPP continues to transmit packets using the
326 old authentication method (unauthenticated or using old sha1 key). If a
327 packet is received, which does not pass the current authentication, then
328 VPP tries to authenticate it using the new method (which might be none,
329 if deactivating authentication) and if it passes, then the new
330 authentication method is put in use.
332 The recommended procedure for enabling/changing/disabling session
335 1. perform authentication change on vpp’s side with delayed option set
337 2. perform authentication change on peer’s side (without delayed option)
341 - if both peers use delayed option at the same time, the change will
342 never be carried out, since none of the peers will see any packet
343 with the new authentication which could trigger the change
344 - remote peer does not need to support or even be aware of this
345 mechanism for it to work properly
350 Echo function is used by VPP whenever a peer declares the willingness to
351 support it, echo-source is set and it contains a usable subnet (see
352 below). When echo function is switched on, the required min rx interval
353 advertised to peer is set to 1 second (or the configured value, if its
359 Because echo packets are only looped back (and not processed in any way)
360 by a peer, it’s necessary to set the source address in a way which
361 avoids packet drop due to spoofing protection by VPP. Per RFC, the
362 source address should not be in the subnet set on the interface over
363 which the echo packets are sent. Also, it must not be any VPP-local
364 address, otherwise the packet gets dropped on receipt by VPP. The
365 solution is to create a loopback interface with a (private) IPv4/IPv6
366 subnet assigned as echo-source. The BFD then picks an unused address
367 from the subnet by flipping the last bit and uses that as source address
368 in the echo packets, thus meeting RFC recommendation while avoiding
371 Example: if 10.10.10.3/31 is the subnet, then 10.10.10.2 will be used as
372 source address in (IPv4) echo packets
377 Demand mode is respected by VPP, but not used locally. The only scenario
378 when demand mode could make sense currently is when echo is active.
379 Because echo packets are inherently insecure against an adversary
380 looping them back a poll sequence would be required for slow periodic
381 connectivity verification anyway. It’s more efficient to just ask the
382 remote peer to send slow periodic control frames without VPP initiating
383 periodic poll sequences.
388 Session may be put admin-down at any time. This immediately causes the
389 state to be changed to AdminDown and remain so unless the session is put
392 BFD implementation notes
393 ------------------------
395 Because BFD can work over different transport layers, the BFD code is
396 separated into core BFD functionality - main module implemented in
397 bfd_main.c and transport-specific code implemented in bfd_udp.c.
402 Main module is responsible for handling all the BFD functionality
408 Internal APIs defined in bfd_main.h are called from transport-specific
409 code to create/modify/delete
414 When a packet is received by the transport layer, it is forwarded to
415 main module (to main thread) via an RPC call. At this point, the
416 authentication has been verified, so the packet is consumed, session
417 parameters are updated accordingly and state change (if applicable).
418 Based on these, the timeouts are adjusted if required and an event is
419 sent to the process node to wake up and recalculate sleep time.
424 Main module allocates a vlib_buffer_t, creates the required BFD frame
425 (control or echo in it), then calls the transport layer to add the
426 transport layer. Then a frame containing the buffer to the appropriate
427 node is created and enqueued.
432 Main module implements one process node which is a simple loop. The
433 process node gets next timeout from the timer wheel, sleeps until the
434 timeout expires and then calls a timeout routine which drives the state
435 machine for each session which timed out. The sleep is interrupted
436 externally via vlib event, when a session is added or modified in a way
437 which might require timer wheel manipulation. In this case the caller
438 inserts the necessary timeout to timer wheel and then signals the
439 process node to wake up early, handle possible timeouts and recalculate
440 the sleep time again.
445 Default state of BFD session when created is Down, per RFC 5880. State
446 changes to Init, Up or Down based on events like received state from
447 peer and timeouts. The session state can be set AdminDown using a binary
448 API, which prevents it from going to any other state, until this
449 limitation is removed. This state is advertised to peers in slow
450 periodic control frames.
452 For each session, the following timeouts are maintained:
454 1. tx timeout - used for sending out control frames
455 2. rx timeout - used for detecting session timeout
456 3. echo tx timeout - used for sending out echo frames
457 4. echo rx timeout - used for detecting session timeout based on echo
459 These timeouts are maintained in cpu clocks and recalculated when
460 appropriate (e.g. rx timeout is bumped when a packet is received,
461 keeping the session alive). Only the earliest timeout is inserted into
462 the timer wheel at a time and timer wheel events are never deleted,
463 rather spurious events are ignored. This allows efficient operation,
464 like not inserting events into timing wheel for each packet received or
465 ignoring left-over events in case a bfd session gets removed and a new
466 one is recreated with the same session index.
468 Authentication keys management
469 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
471 Authentication keys are managed internally in a pool, with each key
472 tracking it’s use count. The removal/modification is only allowed if the
478 UDP module is responsible for:
480 1. public APIs/CLIs to configure BFD over UDP.
481 2. support code called by main module to encapsulate/decapsulate BFD
484 This module implements two graph nodes - for consuming ipv4 and ipv6
485 packets target at BFD ports 3874 and 3875.
487 .. _packet-receipt-1:
492 BFD packet receipt receipt starts in the bfd udp graph nodes. Since the
493 code needs to verify IP/UDP header data, it relies on ip4-local (and
494 ip6-local) nodes to store pointers to the appropriate headers. First,
495 your discriminator is extracted from BFD packet and used to lookup the
496 existing session. In case it’s zero, the pair of IP addresses and
497 sw_if_index is used to lookup session. Then, main module is called to
498 verify the authentication, if present. Afterwards a check is made if the
499 IP/UDP headers are correct. If yes, then an RPC call is made to the main
500 thread to consume the packet and take action upon it.
505 When process node decides that there is a need to transmit the packet,
506 it creates a buffer, fills the BFD frame data in and calls the UDP
507 module to add the transport layer. This is a simple operation for the
508 control frames consisting of just adding UDP/IP headers based on session
509 data. For echo frames, an additional step, looking at the echo-source
510 interface and picking and address is performed and if this fails, then
511 the packet cannot be transmitted and an error is returned to main