src/vnet/bfd/bfd_doc.rst

   1 .. _bfd_doc:
   2
   3 BFD module
   4 ==========
   5
   6 Overview
   7 --------
   8
   9 Bidirectional Forwarding Detection in VPP currently supports single-hop
  10 UDP transport based on RFC 5880 and RFC 5881.
  11
  12 Usage
  13 -----
  14
  15 General usage
  16 ~~~~~~~~~~~~~
  17
  18 BFD sessions are created using APIs only. The following CLIs are
  19 implemented, which call the APIs to manipulate the BFD:
  20
  21 Show commands:
  22 ^^^^^^^^^^^^^^
  23
  24    show bfd [keys|sessions|echo-source]
  25
  26 Show the existing keys, sessions or echo-source.
  27
  28 Key manipulation
  29 ^^^^^^^^^^^^^^^^
  30
  31 Create a new key or modify an existing key
  32 ''''''''''''''''''''''''''''''''''''''''''
  33
  34    bfd key set conf-key-id type <keyed-sha1|meticulous-keyed-sha1>
  35    secret
  36
  37 Parameters:
  38
  39 -  conf-key-id - local configuration key ID, used to uniquely identify
  40    this key
  41 -  type - type of the key
  42 -  secret - shared secret (hex data)
  43
  44 Example:
  45
  46    bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret
  47    69d685b0d990cdba46872706dc
  48
  49 Notes:
  50
  51 -  in-use key cannot be modified
  52
  53 Delete an existing key
  54 ''''''''''''''''''''''
  55
  56    bfd key del conf-key-id
  57
  58 Parameters:
  59
  60 -  conf-key-id - local configuration key ID, used to uniquely identify
  61    this key
  62
  63 Example:
  64
  65    bfd key del conf-key-id 2368880803
  66
  67 Notes:
  68
  69 -  in-use key cannot be deleted
  70
  71 Create a new (plain or authenticated) BFD session
  72 '''''''''''''''''''''''''''''''''''''''''''''''''
  73
  74    bfd udp session add interface local-addr
  75
  76    .. raw:: html
  77
  78       <address>
  79
  80    peer-addr
  81
  82    .. raw:: html
  83
  84       <address>
  85
  86    desired-min-tx required-min-rx detect-mult [ conf-key-id bfd-key-id ]
  87
  88 Parameters:
  89
  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
  98
  99 Example:
 100
 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
 104
 105 Notes:
 106
 107 -  if conf-key-id and bfd-key-id are not specified, session is
 108    non-authenticated
 109 -  desired-min-tx controls desired transmission rate of both control
 110    frames and echo packets
 111
 112 Modify BFD session
 113 ''''''''''''''''''
 114
 115    bfd udp session mod interface local-addr
 116
 117    .. raw:: html
 118
 119       <address>
 120
 121    peer-addr
 122
 123    .. raw:: html
 124
 125       <address>
 126
 127    desired-min-tx required-min-rx detect-mult
 128
 129 Parameters:
 130
 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)
 137
 138 Example:
 139
 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
 142    12
 143
 144 Notes:
 145
 146 -  desired-min-tx controls desired transmission rate of both control
 147    frames and echo packets
 148
 149 Delete an existing BFD session
 150 ''''''''''''''''''''''''''''''
 151
 152    bfd udp session del interface local-addr
 153
 154    .. raw:: html
 155
 156       <address>
 157
 158    peer-addr
 159
 160    .. raw:: html
 161
 162       <address>
 163
 164 Parameters:
 165
 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)
 169
 170 Example:
 171
 172    bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr
 173    172.16.1.2
 174
 175 Set session admin-up or admin-down
 176 ''''''''''''''''''''''''''''''''''
 177
 178    bfd udp session set-flags interface local-addr
 179
 180    .. raw:: html
 181
 182       <address>
 183
 184    peer-addr
 185
 186    .. raw:: html
 187
 188       <address>
 189
 190    admin <up|down>
 191
 192 Parameters:
 193
 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
 198
 199 Example:
 200
 201    bfd udp session set-flags admin down interface pg0 local-addr
 202    172.16.1.1 peer-addr 172.16.1.2
 203
 204 Activate/change authentication for existing session
 205 '''''''''''''''''''''''''''''''''''''''''''''''''''
 206
 207    bfd udp session auth activate interface local-addr
 208
 209    .. raw:: html
 210
 211       <address>
 212
 213    peer-addr
 214
 215    .. raw:: html
 216
 217       <address>
 218
 219    conf-key-id bfd-key-id [ delayed <yes|no> ]
 220
 221 Parameters:
 222
 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
 229    the same action
 230
 231 Example:
 232
 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
 235
 236 Notes:
 237
 238 -  see `Delayed option <#delayed-option>`__ for more information
 239
 240 Deactivate authentication for existing session
 241 ''''''''''''''''''''''''''''''''''''''''''''''
 242
 243    bfd udp session auth deactivate interface local-addr
 244
 245    .. raw:: html
 246
 247       <address>
 248
 249    peer-addr
 250
 251    .. raw:: html
 252
 253       <address>
 254
 255    [ delayed <yes|no> ]
 256
 257 Parameters:
 258
 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
 263    the same action
 264
 265 Example:
 266
 267    bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1
 268    peer-addr 172.16.1.2
 269
 270 Notes:
 271
 272 -  see `Delayed option <#delayed-option>`__ for more information
 273
 274 Set echo-source interface
 275 '''''''''''''''''''''''''
 276
 277    bfd udp echo-source set interface
 278
 279 Parameters:
 280
 281 -  interface - interface used for getting source address for echo
 282    packets
 283
 284 Example:
 285
 286    bfd udp echo-source set interface loop0
 287
 288 Delete echo-source interface
 289 ''''''''''''''''''''''''''''
 290
 291    bfd udp echo-source del
 292
 293 Example:
 294
 295    bfd udp echo-source del
 296
 297 Authentication
 298 ~~~~~~~~~~~~~~
 299
 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
 303 used by sessions.
 304
 305 There are two key IDs in the scope of BFD session:
 306
 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
 309    identifying the key
 310 -  BFD key ID is the key ID carried in BFD control frames and is used
 311    for verifying authentication
 312
 313 Turning auth on/off
 314 ^^^^^^^^^^^^^^^^^^^
 315
 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.
 319
 320 Delayed option
 321 ''''''''''''''
 322
 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.
 331
 332 The recommended procedure for enabling/changing/disabling session
 333 authentication is:
 334
 335 1. perform authentication change on vpp’s side with delayed option set
 336    to yes
 337 2. perform authentication change on peer’s side (without delayed option)
 338
 339 Notes:
 340
 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
 346
 347 Echo function
 348 ~~~~~~~~~~~~~
 349
 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
 354 higher).
 355
 356 Echo source address
 357 ^^^^^^^^^^^^^^^^^^^
 358
 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
 369 spoofing protection.
 370
 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
 373
 374 Demand mode
 375 ~~~~~~~~~~~
 376
 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.
 384
 385 Admin-down
 386 ~~~~~~~~~~
 387
 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
 390 admin-up.
 391
 392 BFD implementation notes
 393 ------------------------
 394
 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.
 398
 399 Main module
 400 ~~~~~~~~~~~
 401
 402 Main module is responsible for handling all the BFD functionality
 403 defined in RFC 5880.
 404
 405 Internal API
 406 ^^^^^^^^^^^^
 407
 408 Internal APIs defined in bfd_main.h are called from transport-specific
 409 code to create/modify/delete
 410
 411 Packet receipt
 412 ^^^^^^^^^^^^^^
 413
 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.
 420
 421 Packet transmit
 422 ^^^^^^^^^^^^^^^
 423
 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.
 428
 429 Process node
 430 ^^^^^^^^^^^^
 431
 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.
 441
 442 State machine
 443 ^^^^^^^^^^^^^
 444
 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.
 451
 452 For each session, the following timeouts are maintained:
 453
 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
 458
 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.
 467
 468 Authentication keys management
 469 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 470
 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
 473 key is not in use.
 474
 475 UDP module
 476 ~~~~~~~~~~
 477
 478 UDP module is responsible for:
 479
 480 1. public APIs/CLIs to configure BFD over UDP.
 481 2. support code called by main module to encapsulate/decapsulate BFD
 482    packets
 483
 484 This module implements two graph nodes - for consuming ipv4 and ipv6
 485 packets target at BFD ports 3874 and 3875.
 486
 487 .. _packet-receipt-1:
 488
 489 Packet receipt
 490 ^^^^^^^^^^^^^^
 491
 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.
 501
 502 Packet transmission
 503 ^^^^^^^^^^^^^^^^^^^
 504
 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
 512 thread.