lib/bfd.h

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