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_GBL_FLAG_IN_SHUTDOWN (1 << 0) /* The daemon in shutdown */
  44 struct bfd_gbl {
  45         uint16_t flags;
  46 };
  47
  48 #define BFD_FLAG_PARAM_CFG (1 << 0) /* parameters have been configured */
  49 #define BFD_FLAG_BFD_REG   (1 << 1) /* Peer registered with BFD */
  50 #define BFD_FLAG_BFD_TYPE_MULTIHOP (1 << 2) /* Peer registered with BFD as multihop */
  51 #define BFD_FLAG_BFD_CBIT_ON (1 << 3) /* Peer registered with CBIT set to on */
  52 #define BFD_FLAG_BFD_CHECK_CONTROLPLANE (1 << 4) /* BFD and controlplane daemon are linked */
  53
  54 #define BFD_STATUS_UNKNOWN    (1 << 0) /* BFD session status never received */
  55 #define BFD_STATUS_DOWN       (1 << 1) /* BFD session status is down */
  56 #define BFD_STATUS_UP         (1 << 2) /* BFD session status is up */
  57 #define BFD_STATUS_ADMIN_DOWN (1 << 3) /* BFD session is admin down */
  58
  59 #define BFD_PROFILE_NAME_LEN 64
  60
  61 #define BFD_SET_CLIENT_STATUS(current_status, new_status)                 \
  62         do {                                                              \
  63                 (current_status) =                                        \
  64                         (((new_status) == BFD_STATUS_ADMIN_DOWN) ?        \
  65                                           BFD_STATUS_DOWN : (new_status));\
  66         } while (0)
  67
  68 enum bfd_sess_type {
  69         BFD_TYPE_NOT_CONFIGURED,
  70         BFD_TYPE_SINGLEHOP,
  71         BFD_TYPE_MULTIHOP
  72 };
  73
  74 struct bfd_info {
  75         uint16_t flags;
  76         uint8_t detect_mult;
  77         uint32_t desired_min_tx;
  78         uint32_t required_min_rx;
  79         time_t last_update;
  80         uint8_t status;
  81         enum bfd_sess_type type;
  82         char profile[BFD_PROFILE_NAME_LEN];
  83 };
  84
  85 extern struct bfd_info *bfd_info_create(void);
  86
  87 extern void bfd_info_free(struct bfd_info **bfd_info);
  88
  89 extern int bfd_validate_param(struct vty *vty, const char *dm_str,
  90                               const char *rx_str, const char *tx_str,
  91                               uint8_t *dm_val, uint32_t *rx_val,
  92                               uint32_t *tx_val);
  93
  94 extern void bfd_set_param(struct bfd_info **bfd_info, uint32_t min_rx,
  95                           uint32_t min_tx, uint8_t detect_mult,
  96                           const char *profile, int defaults, int *command);
  97 extern void bfd_peer_sendmsg(struct zclient *zclient, struct bfd_info *bfd_info,
  98                              int family, void *dst_ip, void *src_ip,
  99                              char *if_name, int ttl, int multihop, int cbit,
 100                              int command, int set_flag, vrf_id_t vrf_id);
 101
 102 extern const char *bfd_get_command_dbg_str(int command);
 103
 104 extern struct interface *bfd_get_peer_info(struct stream *s, struct prefix *dp,
 105                                            struct prefix *sp, int *status,
 106                                            int *remote_cbit,
 107                                            vrf_id_t vrf_id);
 108
 109 const char *bfd_get_status_str(int status);
 110
 111 extern void bfd_show_param(struct vty *vty, struct bfd_info *bfd_info,
 112                            int bfd_tag, int extra_space, bool use_json,
 113                            json_object *json_obj);
 114
 115 extern void bfd_show_info(struct vty *vty, struct bfd_info *bfd_info,
 116                           int multihop, int extra_space, bool use_json,
 117                           json_object *json_obj);
 118
 119 extern void bfd_client_sendmsg(struct zclient *zclient, int command,
 120                                vrf_id_t vrf_id);
 121
 122 extern void bfd_gbl_init(void);
 123
 124 extern void bfd_gbl_exit(void);
 125
 126
 127 /*
 128  * BFD new API.
 129  */
 130
 131 /* Forward declaration of argument struct. */
 132 struct bfd_session_params;
 133
 134 /** Session state definitions. */
 135 enum bfd_session_state {
 136         /** Session state is unknown or not initialized. */
 137         BSS_UNKNOWN = BFD_STATUS_UNKNOWN,
 138         /** Local or remote peer administratively shutdown the session. */
 139         BSS_ADMIN_DOWN = BFD_STATUS_ADMIN_DOWN,
 140         /** Session is down. */
 141         BSS_DOWN = BFD_STATUS_DOWN,
 142         /** Session is up and working correctly. */
 143         BSS_UP = BFD_STATUS_UP,
 144 };
 145
 146 /** BFD session status information */
 147 struct bfd_session_status {
 148         /** Current session state. */
 149         enum bfd_session_state state;
 150         /** Previous session state. */
 151         enum bfd_session_state previous_state;
 152         /** Remote Control Plane Independent bit state. */
 153         bool remote_cbit;
 154         /** Last event occurrence. */
 155         time_t last_event;
 156 };
 157
 158 /**
 159  * Session status update callback.
 160  *
 161  * \param bsp BFD session parameters.
 162  * \param bss BFD session status.
 163  * \param arg application independent data.
 164  */
 165 typedef void (*bsp_status_update)(struct bfd_session_params *bsp,
 166                                   const struct bfd_session_status *bss,
 167                                   void *arg);
 168
 169 /**
 170  * Allocates and initializes the session parameters.
 171  *
 172  * \param updatedb status update notification callback.
 173  * \param args application independent data.
 174  *
 175  * \returns pointer to configuration storage.
 176  */
 177 struct bfd_session_params *bfd_sess_new(bsp_status_update updatecb, void *args);
 178
 179 /**
 180  * Uninstall session if installed and free resources allocated by the
 181  * parameters. Already sets pointer to `NULL` to avoid dangling references.
 182  *
 183  * \param bsp session parameters.
 184  */
 185 void bfd_sess_free(struct bfd_session_params **bsp);
 186
 187 /**
 188  * Enable/disable session installation.
 189  *
 190  * \param bsp session parameters.
 191  * \param enable knob variable.
 192  */
 193 void bfd_sess_enable(struct bfd_session_params *bsp, bool enable);
 194
 195 /**
 196  * Set the local and peer address of the BFD session.
 197  *
 198  * \param bsp BFD session parameters.
 199  * \param src local address (optional, can be `NULL`).
 200  * \param dst remote address (mandatory).
 201  */
 202 void bfd_sess_set_ipv4_addrs(struct bfd_session_params *bsp,
 203                              struct in_addr *src, struct in_addr *dst);
 204
 205 /**
 206  * Set the local and peer address of the BFD session.
 207  *
 208  * \param bsp BFD session parameters.
 209  * \param src local address (optional, can be `NULL`).
 210  * \param dst remote address (mandatory).
 211  */
 212 void bfd_sess_set_ipv6_addrs(struct bfd_session_params *bsp,
 213                              struct in6_addr *src, struct in6_addr *dst);
 214
 215 /**
 216  * Configure the BFD session interface.
 217  *
 218  * \param bsp BFD session parameters.
 219  * \param ifname interface name (or `NULL` to remove it).
 220  */
 221 void bfd_sess_set_interface(struct bfd_session_params *bsp, const char *ifname);
 222
 223 /**
 224  * Configure the BFD session profile name.
 225  *
 226  * \param bsp BFD session parameters.
 227  * \param profile profile name (or `NULL` to remove it).
 228  */
 229 void bfd_sess_set_profile(struct bfd_session_params *bsp, const char *profile);
 230
 231 /**
 232  * Configure the BFD session VRF.
 233  *
 234  * \param bsp BFD session parameters.
 235  * \param vrf_id the VRF identification number.
 236  */
 237 void bfd_sess_set_vrf(struct bfd_session_params *bsp, vrf_id_t vrf_id);
 238
 239 /**
 240  * Configure the BFD session single/multi hop setting.
 241  *
 242  * \param bsp BFD session parameters.
 243  * \param min_ttl minimum TTL value expected (255 for single hop, 254 for
 244  *                multi hop with single hop, 253 for multi hop with two hops
 245  *                and so on). See `BFD_SINGLE_HOP_TTL` and
 246  *                `BFD_MULTI_HOP_MIN_TTL` for defaults.
 247  *
 248  * To simplify things if your protocol only knows the amount of hops it is
 249  * better to use `bfd_sess_set_hops` instead.
 250  */
 251 void bfd_sess_set_mininum_ttl(struct bfd_session_params *bsp, uint8_t min_ttl);
 252
 253 /** To use single hop the minimum TTL must be set to this. */
 254 #define BFD_SINGLE_HOP_TTL 255
 255 /** To use multi hop the minimum TTL must be set to this or less. */
 256 #define BFD_MULTI_HOP_MIN_TTL 254
 257
 258 /**
 259  * This function is the inverted version of `bfd_sess_set_minimum_ttl`.
 260  * Instead of receiving the minimum expected TTL, it receives the amount of
 261  * hops the protocol will jump.
 262  *
 263  * \param bsp BFD session parameters.
 264  * \param min_ttl minimum amount of hops expected (1 for single hop, 2 or
 265  *                more for multi hop).
 266  */
 267 void bfd_sess_set_hop_count(struct bfd_session_params *bsp, uint8_t min_ttl);
 268
 269 /**
 270  * Configure the BFD session to set the Control Plane Independent bit.
 271  *
 272  * \param bsp BFD session parameters.
 273  * \param enable BFD Control Plane Independent state.
 274  */
 275 void bfd_sess_set_cbit(struct bfd_session_params *bsp, bool enable);
 276
 277 /**
 278  * DEPRECATED: please avoid using timers directly and use profiles instead.
 279  *
 280  * Configures the BFD session timers to use. This is specially useful with
 281  * `ptm-bfd` which does not support timers.
 282  *
 283  * \param bsp BFD session parameters.
 284  * \param detection_multiplier the detection multiplier value.
 285  * \param min_rx minimum required receive period.
 286  * \param min_tx minimum required transmission period.
 287  */
 288 void bfd_sess_set_timers(struct bfd_session_params *bsp,
 289                          uint8_t detection_multiplier, uint32_t min_rx,
 290                          uint32_t min_tx);
 291
 292 /**
 293  * Installs or updates the BFD session based on the saved session arguments.
 294  *
 295  * \param bsp session parameters.
 296  */
 297 void bfd_sess_install(struct bfd_session_params *bsp);
 298
 299 /**
 300  * Uninstall the BFD session based on the saved session arguments.
 301  *
 302  * \param bsp session parameters.
 303  */
 304 void bfd_sess_uninstall(struct bfd_session_params *bsp);
 305
 306 /**
 307  * Get BFD session current status.
 308  *
 309  * \param bsp session parameters.
 310  *
 311  * \returns BFD session status data structure.
 312  */
 313 enum bfd_session_state bfd_sess_status(const struct bfd_session_params *bsp);
 314
 315 /**
 316  * Get BFD session minimum TTL configured value.
 317  *
 318  * \param bsp session parameters.
 319  *
 320  * \returns configured minimum TTL.
 321  */
 322 uint8_t bfd_sess_minimum_ttl(const struct bfd_session_params *bsp);
 323
 324 /**
 325  * Inverted version of `bfd_sess_minimum_ttl`. Gets the amount of hops in the
 326  * way to the peer.
 327  *
 328  * \param bsp session parameters.
 329  *
 330  * \returns configured amount of hops.
 331  */
 332 uint8_t bfd_sess_hop_count(const struct bfd_session_params *bsp);
 333
 334 /**
 335  * Get BFD session profile configured value.
 336  *
 337  * \param bsp session parameters.
 338  *
 339  * \returns configured profile name (or `NULL` if empty).
 340  */
 341 const char *bfd_sess_profile(const struct bfd_session_params *bsp);
 342
 343 /**
 344  * Get BFD session addresses.
 345  *
 346  * \param bsp session parameters.
 347  * \param family the address family being used (AF_INET or AF_INET6).
 348  * \param src source address (optional, may be `NULL`).
 349  * \param dst peer address (optional, may be `NULL`).
 350  */
 351 void bfd_sess_addresses(const struct bfd_session_params *bsp, int *family,
 352                         struct in6_addr *src, struct in6_addr *dst);
 353 /**
 354  * Get BFD session interface name.
 355  *
 356  * \param bsp session parameters.
 357  *
 358  * \returns `NULL` if not set otherwise the interface name.
 359  */
 360 const char *bfd_sess_interface(const struct bfd_session_params *bsp);
 361
 362 /**
 363  * Get BFD session VRF name.
 364  *
 365  * \param bsp session parameters.
 366  *
 367  * \returns the VRF name.
 368  */
 369 const char *bfd_sess_vrf(const struct bfd_session_params *bsp);
 370
 371 /**
 372  * Get BFD session VRF ID.
 373  *
 374  * \param bsp session parameters.
 375  *
 376  * \returns the VRF name.
 377  */
 378 vrf_id_t bfd_sess_vrf_id(const struct bfd_session_params *bsp);
 379
 380 /**
 381  * Get BFD session control plane independent bit configuration state.
 382  *
 383  * \param bsp session parameters.
 384  *
 385  * \returns `true` if enabled otherwise `false`.
 386  */
 387 bool bfd_sess_cbit(const struct bfd_session_params *bsp);
 388
 389 /**
 390  * DEPRECATED: please avoid using timers directly and use profiles instead.
 391  *
 392  * Gets the configured timers.
 393  *
 394  * \param bsp BFD session parameters.
 395  * \param detection_multiplier the detection multiplier value.
 396  * \param min_rx minimum required receive period.
 397  * \param min_tx minimum required transmission period.
 398  */
 399 void bfd_sess_timers(const struct bfd_session_params *bsp,
 400                      uint8_t *detection_multiplier, uint32_t *min_rx,
 401                      uint32_t *min_tx);
 402
 403 /**
 404  * Show BFD session configuration and status. If `json` is provided (e.g. not
 405  * `NULL`) then information will be inserted in object, otherwise printed to
 406  * `vty`.
 407  *
 408  * \param vty Pointer to `vty` for outputting text.
 409  * \param json (optional) JSON object pointer.
 410  * \param bsp session parameters.
 411  */
 412 void bfd_sess_show(struct vty *vty, struct json_object *json,
 413                    struct bfd_session_params *bsp);
 414
 415 /**
 416  * Initializes the BFD integration library. This function executes the
 417  * following actions:
 418  *
 419  * - Copy the `struct thread_master` pointer to use as "thread" to execute
 420  *   the BFD session parameters installation.
 421  * - Copy the `struct zclient` pointer to install its callbacks.
 422  * - Initializes internal data structures.
 423  *
 424  * \param tm normally the daemon main thread event manager.
 425  * \param zc the zebra client of the daemon.
 426  */
 427 void bfd_protocol_integration_init(struct zclient *zc,
 428                                    struct thread_master *tm);
 429
 430 /**
 431  * BFD session registration arguments.
 432  */
 433 struct bfd_session_arg {
 434         /**
 435          * BFD command.
 436          *
 437          * Valid commands:
 438          * - `ZEBRA_BFD_DEST_REGISTER`
 439          * - `ZEBRA_BFD_DEST_DEREGISTER`
 440          */
 441         int32_t command;
 442
 443         /**
 444          * BFD family type.
 445          *
 446          * Supported types:
 447          * - `AF_INET`
 448          * - `AF_INET6`.
 449          */
 450         uint32_t family;
 451         /** Source address. */
 452         struct in6_addr src;
 453         /** Source address. */
 454         struct in6_addr dst;
 455
 456         /** Multi hop indicator. */
 457         uint8_t mhop;
 458         /** Expected TTL. */
 459         uint8_t ttl;
 460         /** C bit (Control Plane Independent bit) indicator. */
 461         uint8_t cbit;
 462
 463         /** Interface name size. */
 464         uint8_t ifnamelen;
 465         /** Interface name. */
 466         char ifname[64];
 467
 468         /** Daemon or session VRF. */
 469         vrf_id_t vrf_id;
 470
 471         /** Profile name length. */
 472         uint8_t profilelen;
 473         /** Profile name. */
 474         char profile[BFD_PROFILE_NAME_LEN];
 475
 476         /*
 477          * Deprecation fields: these fields should be removed once `ptm-bfd`
 478          * no longer uses this interface.
 479          */
 480
 481         /** Minimum required receive interval (in microseconds). */
 482         uint32_t min_rx;
 483         /** Minimum desired transmission interval (in microseconds). */
 484         uint32_t min_tx;
 485         /** Detection multiplier. */
 486         uint32_t detection_multiplier;
 487
 488         /** BFD client information output. */
 489         struct bfd_info *bfd_info;
 490
 491         /** Write registration indicator. */
 492         uint8_t set_flag;
 493 };
 494
 495 /**
 496  * Send a message to BFD daemon through the zebra client.
 497  *
 498  * \param zc the zebra client context.
 499  * \param arg the BFD session command arguments.
 500  *
 501  * \returns `-1` on failure otherwise `0`.
 502  *
 503  * \see bfd_session_arg.
 504  */
 505 extern int zclient_bfd_command(struct zclient *zc, struct bfd_session_arg *arg);
 506
 507 /**
 508  * Enables or disables BFD protocol integration API debugging.
 509  *
 510  * \param enable new API debug state.
 511  */
 512 extern void bfd_protocol_integration_set_debug(bool enable);
 513
 514 /**
 515  * Sets shutdown mode so no more events are processed.
 516  *
 517  * This is useful to avoid the event storm that happens caused by network,
 518  * interfaces or VRFs removal. It should also avoid some crashes due hanging
 519  * pointers left overs by protocol.
 520  *
 521  * \param enable new API shutdown state.
 522  */
 523 extern void bfd_protocol_integration_set_shutdown(bool enable);
 524
 525 /**
 526  * Get API debugging state.
 527  */
 528 extern bool bfd_protocol_integration_debug(void);
 529
 530 /**
 531  * Get API shutdown state.
 532  */
 533 extern bool bfd_protocol_integration_shutting_down(void);
 534
 535 #ifdef __cplusplus
 536 }
 537 #endif
 538
 539 #endif /* _ZEBRA_BFD_H */