lib/bfd.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /**
   3  * bfd.h: BFD definitions and structures
   4  *
   5  * @copyright Copyright (C) 2015 Cumulus Networks, Inc.
   6  */
   7
   8 #ifndef _ZEBRA_BFD_H
   9 #define _ZEBRA_BFD_H
  10
  11 #include "lib/json.h"
  12 #include "lib/zclient.h"
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 #define BFD_DEF_MIN_RX 300
  19 #define BFD_MIN_MIN_RX 50
  20 #define BFD_MAX_MIN_RX 60000
  21 #define BFD_DEF_MIN_TX 300
  22 #define BFD_MIN_MIN_TX 50
  23 #define BFD_MAX_MIN_TX 60000
  24 #define BFD_DEF_DETECT_MULT 3
  25 #define BFD_MIN_DETECT_MULT 2
  26 #define BFD_MAX_DETECT_MULT 255
  27
  28 #define BFD_STATUS_UNKNOWN    (1 << 0) /* BFD session status never received */
  29 #define BFD_STATUS_DOWN       (1 << 1) /* BFD session status is down */
  30 #define BFD_STATUS_UP         (1 << 2) /* BFD session status is up */
  31 #define BFD_STATUS_ADMIN_DOWN (1 << 3) /* BFD session is admin down */
  32
  33 #define BFD_PROFILE_NAME_LEN 64
  34
  35 const char *bfd_get_status_str(int status);
  36
  37 extern void bfd_client_sendmsg(struct zclient *zclient, int command,
  38                                vrf_id_t vrf_id);
  39
  40 /*
  41  * BFD new API.
  42  */
  43
  44 /* Forward declaration of argument struct. */
  45 struct bfd_session_params;
  46
  47 /** Session state definitions. */
  48 enum bfd_session_state {
  49         /** Session state is unknown or not initialized. */
  50         BSS_UNKNOWN = BFD_STATUS_UNKNOWN,
  51         /** Local or remote peer administratively shutdown the session. */
  52         BSS_ADMIN_DOWN = BFD_STATUS_ADMIN_DOWN,
  53         /** Session is down. */
  54         BSS_DOWN = BFD_STATUS_DOWN,
  55         /** Session is up and working correctly. */
  56         BSS_UP = BFD_STATUS_UP,
  57 };
  58
  59 /** BFD session status information */
  60 struct bfd_session_status {
  61         /** Current session state. */
  62         enum bfd_session_state state;
  63         /** Previous session state. */
  64         enum bfd_session_state previous_state;
  65         /** Remote Control Plane Independent bit state. */
  66         bool remote_cbit;
  67         /** Last event occurrence. */
  68         time_t last_event;
  69 };
  70
  71 /**
  72  * Session status update callback.
  73  *
  74  * \param bsp BFD session parameters.
  75  * \param bss BFD session status.
  76  * \param arg application independent data.
  77  */
  78 typedef void (*bsp_status_update)(struct bfd_session_params *bsp,
  79                                   const struct bfd_session_status *bss,
  80                                   void *arg);
  81
  82 /**
  83  * Allocates and initializes the session parameters.
  84  *
  85  * \param updatecb status update notification callback.
  86  * \param args application independent data.
  87  *
  88  * \returns pointer to configuration storage.
  89  */
  90 struct bfd_session_params *bfd_sess_new(bsp_status_update updatecb, void *args);
  91
  92 /**
  93  * Uninstall session if installed and free resources allocated by the
  94  * parameters. Already sets pointer to `NULL` to avoid dangling references.
  95  *
  96  * \param bsp session parameters.
  97  */
  98 void bfd_sess_free(struct bfd_session_params **bsp);
  99
 100 /**
 101  * Set the local and peer address of the BFD session.
 102  *
 103  * NOTE:
 104  * If the address changed the session is removed and must be installed again
 105  * with `bfd_sess_install`.
 106  *
 107  * \param bsp BFD session parameters.
 108  * \param src local address (optional, can be `NULL`).
 109  * \param dst remote address (mandatory).
 110  */
 111 void bfd_sess_set_ipv4_addrs(struct bfd_session_params *bsp,
 112                              const struct in_addr *src,
 113                              const struct in_addr *dst);
 114
 115 /**
 116  * Set the local and peer address of the BFD session.
 117  *
 118  * NOTE:
 119  * If the address changed the session is removed and must be installed again
 120  * with `bfd_sess_install`.
 121  *
 122  * \param bsp BFD session parameters.
 123  * \param src local address (optional, can be `NULL`).
 124  * \param dst remote address (mandatory).
 125  */
 126 void bfd_sess_set_ipv6_addrs(struct bfd_session_params *bsp,
 127                              const struct in6_addr *src,
 128                              const struct in6_addr *dst);
 129
 130 /**
 131  * Configure the BFD session interface.
 132  *
 133  * NOTE:
 134  * If the interface changed the session is removed and must be installed again
 135  * with `bfd_sess_install`.
 136  *
 137  * \param bsp BFD session parameters.
 138  * \param ifname interface name (or `NULL` to remove it).
 139  */
 140 void bfd_sess_set_interface(struct bfd_session_params *bsp, const char *ifname);
 141
 142 /**
 143  * Configure the BFD session profile name.
 144  *
 145  * NOTE:
 146  * Session profile will only change after a `bfd_sess_install`.
 147  *
 148  * \param bsp BFD session parameters.
 149  * \param profile profile name (or `NULL` to remove it).
 150  */
 151 void bfd_sess_set_profile(struct bfd_session_params *bsp, const char *profile);
 152
 153 /**
 154  * Configure the BFD session VRF.
 155  *
 156  * NOTE:
 157  * If the VRF changed the session is removed and must be installed again
 158  * with `bfd_sess_install`.
 159  *
 160  * \param bsp BFD session parameters.
 161  * \param vrf_id the VRF identification number.
 162  */
 163 void bfd_sess_set_vrf(struct bfd_session_params *bsp, vrf_id_t vrf_id);
 164
 165 /**
 166  * Configure the BFD session single/multi hop setting.
 167  *
 168  * NOTE:
 169  * If the number of hops is changed the session is removed and must be
 170  * installed again with `bfd_sess_install`.
 171  *
 172  * \param bsp BFD session parameters.
 173  * \param hops maximum amount of hops expected (1 for single hop, 2 or
 174  *             more for multi hop).
 175  */
 176 void bfd_sess_set_hop_count(struct bfd_session_params *bsp, uint8_t hops);
 177
 178 /**
 179  * Configure the BFD session to set the Control Plane Independent bit.
 180  *
 181  * NOTE:
 182  * Session CPI bit will only change after a `bfd_sess_install`.
 183  *
 184  * \param bsp BFD session parameters.
 185  * \param enable BFD Control Plane Independent state.
 186  */
 187 void bfd_sess_set_cbit(struct bfd_session_params *bsp, bool enable);
 188
 189 /**
 190  * DEPRECATED: please avoid using timers directly and use profiles instead.
 191  *
 192  * Configures the BFD session timers to use. This is specially useful with
 193  * `ptm-bfd` which does not support timers.
 194  *
 195  * NOTE:
 196  * Session timers will only apply if the session has not been created yet.
 197  * If the session is already installed you must uninstall and install again
 198  * to take effect.
 199  *
 200  * \param bsp BFD session parameters.
 201  * \param detection_multiplier the detection multiplier value.
 202  * \param min_rx minimum required receive period.
 203  * \param min_tx minimum required transmission period.
 204  */
 205 void bfd_sess_set_timers(struct bfd_session_params *bsp,
 206                          uint8_t detection_multiplier, uint32_t min_rx,
 207                          uint32_t min_tx);
 208
 209 /**
 210  * Configures the automatic source selection for the BFD session.
 211  *
 212  * NOTE:
 213  * Setting this configuration will override the IP source value set by
 214  * `bfd_sess_set_ipv4_addrs` or `bfd_sess_set_ipv6_addrs`.
 215  *
 216  * \param bsp BFD session parameters
 217  * \param enable BFD automatic source selection state.
 218  */
 219 void bfd_sess_set_auto_source(struct bfd_session_params *bsp, bool enable);
 220
 221 /**
 222  * Installs or updates the BFD session based on the saved session arguments.
 223  *
 224  * NOTE:
 225  * This function has a delayed effect: it will only install/update after
 226  * all northbound/CLI command batch finishes.
 227  *
 228  * \param bsp session parameters.
 229  */
 230 void bfd_sess_install(struct bfd_session_params *bsp);
 231
 232 /**
 233  * Uninstall the BFD session based on the saved session arguments.
 234  *
 235  * NOTE:
 236  * This function uninstalls the session immediately (if installed) and cancels
 237  * any previous `bfd_sess_install` calls.
 238  *
 239  * \param bsp session parameters.
 240  */
 241 void bfd_sess_uninstall(struct bfd_session_params *bsp);
 242
 243 /**
 244  * Get BFD session current status.
 245  *
 246  * \param bsp session parameters.
 247  *
 248  * \returns BFD session status data structure.
 249  */
 250 enum bfd_session_state bfd_sess_status(const struct bfd_session_params *bsp);
 251
 252 /**
 253  * Get BFD session amount of hops configured value.
 254  *
 255  * \param bsp session parameters.
 256  *
 257  * \returns configured amount of hops.
 258  */
 259 uint8_t bfd_sess_hop_count(const struct bfd_session_params *bsp);
 260
 261 /**
 262  * Get BFD session profile configured value.
 263  *
 264  * \param bsp session parameters.
 265  *
 266  * \returns configured profile name (or `NULL` if empty).
 267  */
 268 const char *bfd_sess_profile(const struct bfd_session_params *bsp);
 269
 270 /**
 271  * Get BFD session addresses.
 272  *
 273  * \param bsp session parameters.
 274  * \param family the address family being used (AF_INET or AF_INET6).
 275  * \param src source address (optional, may be `NULL`).
 276  * \param dst peer address (optional, may be `NULL`).
 277  */
 278 void bfd_sess_addresses(const struct bfd_session_params *bsp, int *family,
 279                         struct in6_addr *src, struct in6_addr *dst);
 280 /**
 281  * Get BFD session interface name.
 282  *
 283  * \param bsp session parameters.
 284  *
 285  * \returns `NULL` if not set otherwise the interface name.
 286  */
 287 const char *bfd_sess_interface(const struct bfd_session_params *bsp);
 288
 289 /**
 290  * Get BFD session VRF name.
 291  *
 292  * \param bsp session parameters.
 293  *
 294  * \returns the VRF name.
 295  */
 296 const char *bfd_sess_vrf(const struct bfd_session_params *bsp);
 297
 298 /**
 299  * Get BFD session VRF ID.
 300  *
 301  * \param bsp session parameters.
 302  *
 303  * \returns the VRF name.
 304  */
 305 vrf_id_t bfd_sess_vrf_id(const struct bfd_session_params *bsp);
 306
 307 /**
 308  * Get BFD session control plane independent bit configuration state.
 309  *
 310  * \param bsp session parameters.
 311  *
 312  * \returns `true` if enabled otherwise `false`.
 313  */
 314 bool bfd_sess_cbit(const struct bfd_session_params *bsp);
 315
 316 /**
 317  * DEPRECATED: please avoid using timers directly and use profiles instead.
 318  *
 319  * Gets the configured timers.
 320  *
 321  * \param bsp BFD session parameters.
 322  * \param detection_multiplier the detection multiplier value.
 323  * \param min_rx minimum required receive period.
 324  * \param min_tx minimum required transmission period.
 325  */
 326 void bfd_sess_timers(const struct bfd_session_params *bsp,
 327                      uint8_t *detection_multiplier, uint32_t *min_rx,
 328                      uint32_t *min_tx);
 329
 330 /**
 331  * Gets the automatic source selection state.
 332  */
 333 bool bfd_sess_auto_source(const struct bfd_session_params *bsp);
 334
 335 /**
 336  * Show BFD session configuration and status. If `json` is provided (e.g. not
 337  * `NULL`) then information will be inserted in object, otherwise printed to
 338  * `vty`.
 339  *
 340  * \param vty Pointer to `vty` for outputting text.
 341  * \param json (optional) JSON object pointer.
 342  * \param bsp session parameters.
 343  */
 344 void bfd_sess_show(struct vty *vty, struct json_object *json,
 345                    struct bfd_session_params *bsp);
 346
 347 /**
 348  * Initializes the BFD integration library. This function executes the
 349  * following actions:
 350  *
 351  * - Copy the `struct thread_master` pointer to use as "thread" to execute
 352  *   the BFD session parameters installation.
 353  * - Copy the `struct zclient` pointer to install its callbacks.
 354  * - Initializes internal data structures.
 355  *
 356  * \param tm normally the daemon main thread event manager.
 357  * \param zc the zebra client of the daemon.
 358  */
 359 void bfd_protocol_integration_init(struct zclient *zc,
 360                                    struct thread_master *tm);
 361
 362 /**
 363  * BFD session registration arguments.
 364  */
 365 struct bfd_session_arg {
 366         /**
 367          * BFD command.
 368          *
 369          * Valid commands:
 370          * - `ZEBRA_BFD_DEST_REGISTER`
 371          * - `ZEBRA_BFD_DEST_DEREGISTER`
 372          */
 373         int32_t command;
 374
 375         /**
 376          * BFD family type.
 377          *
 378          * Supported types:
 379          * - `AF_INET`
 380          * - `AF_INET6`.
 381          */
 382         uint32_t family;
 383         /** Source address. */
 384         struct in6_addr src;
 385         /** Source address. */
 386         struct in6_addr dst;
 387
 388         /** Multi hop indicator. */
 389         uint8_t mhop;
 390         /** Expected hops. */
 391         uint8_t hops;
 392         /** C bit (Control Plane Independent bit) indicator. */
 393         uint8_t cbit;
 394
 395         /** Interface name size. */
 396         uint8_t ifnamelen;
 397         /** Interface name. */
 398         char ifname[64];
 399
 400         /** Daemon or session VRF. */
 401         vrf_id_t vrf_id;
 402
 403         /** Profile name length. */
 404         uint8_t profilelen;
 405         /** Profile name. */
 406         char profile[BFD_PROFILE_NAME_LEN];
 407
 408         /*
 409          * Deprecation fields: these fields should be removed once `ptm-bfd`
 410          * no longer uses this interface.
 411          */
 412
 413         /** Minimum required receive interval (in microseconds). */
 414         uint32_t min_rx;
 415         /** Minimum desired transmission interval (in microseconds). */
 416         uint32_t min_tx;
 417         /** Detection multiplier. */
 418         uint32_t detection_multiplier;
 419 };
 420
 421 /**
 422  * Send a message to BFD daemon through the zebra client.
 423  *
 424  * \param zc the zebra client context.
 425  * \param arg the BFD session command arguments.
 426  *
 427  * \returns `-1` on failure otherwise `0`.
 428  *
 429  * \see bfd_session_arg.
 430  */
 431 extern int zclient_bfd_command(struct zclient *zc, struct bfd_session_arg *arg);
 432
 433 /**
 434  * Enables or disables BFD protocol integration API debugging.
 435  *
 436  * \param enable new API debug state.
 437  */
 438 extern void bfd_protocol_integration_set_debug(bool enable);
 439
 440 /**
 441  * Sets shutdown mode so no more events are processed.
 442  *
 443  * This is useful to avoid the event storm that happens caused by network,
 444  * interfaces or VRFs removal. It should also avoid some crashes due hanging
 445  * pointers left overs by protocol.
 446  *
 447  * \param enable new API shutdown state.
 448  */
 449 extern void bfd_protocol_integration_set_shutdown(bool enable);
 450
 451 /**
 452  * Get API debugging state.
 453  */
 454 extern bool bfd_protocol_integration_debug(void);
 455
 456 /**
 457  * Get API shutdown state.
 458  */
 459 extern bool bfd_protocol_integration_shutting_down(void);
 460
 461 /* Update nexthop-tracking (nht) information for BFD auto source selection.
 462  * The function must be called from the daemon callback function
 463  * that deals with the ZEBRA_NEXTHOP_UPDATE zclient command
 464  */
 465 extern int bfd_nht_update(const struct prefix *match,
 466                           const struct zapi_route *route);
 467
 468 #ifdef __cplusplus
 469 }
 470 #endif
 471
 472 #endif /* _ZEBRA_BFD_H */