src/vnet/ip-neighbor/ip_neighbor.api

   1 /* Hey Emacs use -*- mode: C -*- */
   2 /*
   3  * Copyright (c) 2018 Cisco and/or its affiliates.
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /** \file
  18
  19     This file defines vpp IP neighbor control-plane API messages which are generally
  20     called through a shared memory interface.
  21 */
  22
  23 option version = "1.0.1";
  24
  25 import "vnet/ip/ip_types.api";
  26 import "vnet/ethernet/ethernet_types.api";
  27 import "vnet/interface_types.api";
  28
  29 /** \brief IP neighbor flags
  30     @param is_static - A static neighbor Entry - there are not flushed
  31                        If the interface goes down.
  32     @param is_no_fib_entry - Do not create a corresponding entry in the FIB
  33                            table for the neighbor.
  34 */
  35 enum ip_neighbor_flags: u8
  36 {
  37   IP_API_NEIGHBOR_FLAG_NONE = 0,
  38   IP_API_NEIGHBOR_FLAG_STATIC = 0x1,
  39   IP_API_NEIGHBOR_FLAG_NO_FIB_ENTRY = 0x2,
  40 };
  41
  42 /** \brief IP neighbor
  43     @param sw_if_index - interface used to reach neighbor
  44     @param flags - flags for the neighbor
  45     @param mac_address - l2 address of the neighbor
  46     @param ip_address - ip4 or ip6 address of the neighbor
  47 */
  48 typedef ip_neighbor {
  49   vl_api_interface_index_t sw_if_index;
  50   vl_api_ip_neighbor_flags_t flags;
  51   vl_api_mac_address_t mac_address;
  52   vl_api_address_t ip_address;
  53 };
  54
  55 /** \brief IP neighbor add / del request
  56     @param client_index - opaque cookie to identify the sender
  57     @param context - sender context, to match reply w/ request
  58     @param is_add - 1 to add neighbor, 0 to delete
  59     @param neighbor - the neighbor to add/remove
  60 */
  61 define ip_neighbor_add_del
  62 {
  63   u32 client_index;
  64   u32 context;
  65   /* 1 = add, 0 = delete */
  66   bool is_add;
  67   vl_api_ip_neighbor_t neighbor;
  68 };
  69 /** \brief IP neighbor add / del reply
  70     @param client_index - opaque cookie to identify the sender
  71     @param context - sender context, to match reply w/ request
  72     @param retval - return value
  73     @param stats_index - the index to use for this neighbor in the stats segment
  74 */
  75 define ip_neighbor_add_del_reply
  76 {
  77   u32 context;
  78   i32 retval;
  79   u32 stats_index;
  80 };
  81
  82 /** \brief Dump IP neighbors
  83     @param client_index - opaque cookie to identify the sender
  84     @param context - sender context, to match reply w/ request
  85     @param sw_if_index - the interface to dump neighbors, ~0 == all
  86     @param af - address family is ipv[6|4]
  87 */
  88 define ip_neighbor_dump
  89 {
  90   u32 client_index;
  91   u32 context;
  92   vl_api_interface_index_t sw_if_index  [default=0xffffffff];
  93   vl_api_address_family_t af;
  94 };
  95
  96 /** \brief IP neighbors dump response
  97     @param context - sender context which was passed in the request
  98     @param age - time between last update and sending this message, in seconds
  99     @param neighbour - the neighbor
 100 */
 101 define ip_neighbor_details {
 102   u32 context;
 103   f64 age;
 104   vl_api_ip_neighbor_t neighbor;
 105 };
 106
 107 /** \brief Enable/disable periodic IP neighbor scan
 108     @param client_index - opaque cookie to identify the sender
 109     @param context - sender context, to match reply w/ request
 110     @param af - Address family v4/v6
 111     @param max_number - The maximum number of neighbours that will be created.
 112                          default 50k
 113     @param max_age - The maximum age (in seconds) before an inactive neighbour
 114                      is flushed
 115                          default 0 => never
 116     @param recycle - If max_number of neighbours is reached and new ones need
 117                       to be created should the oldest neighbour be 'recycled'.
 118 */
 119 autoreply define ip_neighbor_config
 120 {
 121   u32 client_index;
 122   u32 context;
 123   vl_api_address_family_t af;
 124   u32 max_number;
 125   u32 max_age;
 126   bool recycle;
 127 };
 128
 129 /** \brief Get neighbor database configuration per AF
 130     @param client_index - opaque cookie to identify the sender
 131     @param context - sender context, to match reply w/ request
 132     @param af - Address family (v4/v6)
 133 */
 134 define ip_neighbor_config_get
 135 {
 136   option in_progress;
 137   u32 client_index;
 138   u32 context;
 139   vl_api_address_family_t af;
 140 };
 141
 142 /** \brief Neighbor database configuration reply
 143     @param context - sender context, to match reply w/ request
 144     @param retval - error (0 is "no error")
 145     @param af - Address family (v4/v6)
 146     @param max_number - The maximum number of neighbours that will be created
 147     @param max_age - The maximum age (in seconds) before an inactive neighbour
 148                      is flushed
 149     @param recycle - If max_number of neighbours is reached and new ones need
 150                       to be created, should the oldest neighbour be 'recycled'
 151 */
 152 define ip_neighbor_config_get_reply
 153 {
 154   option in_progress;
 155   u32 context;
 156   i32 retval;
 157   vl_api_address_family_t af;
 158   u32 max_number;
 159   u32 max_age;
 160   bool recycle;
 161 };
 162
 163 /** \brief IP neighbour replace begin
 164
 165     The use-case is that, for some unspecified reason, the control plane
 166     has a different set of neighbours it than VPP
 167     currently has. The CP would thus like to 'replace' VPP's set
 168     only by specifying what the new set shall be, i.e. it is not
 169     going to delete anything that already exists, rather, it wants any
 170     unspecified neighbors deleted implicitly.
 171     The CP declares the start of this procedure with this replace_begin
 172     API Call, and when it has populated all neighbours it wants, it calls
 173     the below replace_end API. From this point on it is of course free
 174     to add and delete neighbours as usual.
 175     The underlying mechanism by which VPP implements this replace is
 176     intentionally left unspecified.
 177
 178     @param client_index - opaque cookie to identify the sender
 179     @param context - sender context, to match reply w/ request
 180 */
 181 autoreply define ip_neighbor_replace_begin
 182 {
 183   u32 client_index;
 184   u32 context;
 185 };
 186
 187 /** \brief IP neighbour replace end
 188
 189     see ip_neighbor_replace_begin description.
 190
 191     @param client_index - opaque cookie to identify the sender
 192     @param context - sender context, to match reply w/ request
 193 */
 194 autoreply define ip_neighbor_replace_end
 195 {
 196   u32 client_index;
 197   u32 context;
 198 };
 199
 200 /** \brief IP neighbor flush request - removes *all* neighbours.
 201      dynamic and static from API/CLI and dynamic from data-plane.
 202
 203     @param client_index - opaque cookie to identify the sender
 204     @param context - sender context, to match reply w/ request
 205     @param af - Flush neighbours of this address family
 206     @param sw_if_index - Flush on this interface (~0 => all interfaces)
 207 */
 208 autoreply define ip_neighbor_flush
 209 {
 210   u32 client_index;
 211   u32 context;
 212   vl_api_address_family_t af;
 213   vl_api_interface_index_t sw_if_index [default=0xffffffff];
 214 };
 215
 216 /** \brief Register for IP neighbour events creation
 217     @param client_index - opaque cookie to identify the sender
 218     @param context - sender context, to match reply w/ request
 219     @param enable - 1 => register for events, 0 => cancel registration
 220     @param pid - sender's pid
 221     @param ip - exact IP address of interested neighbor resolution event
 222     @param sw_if_index - interface on which the IP address is present.
 223 */
 224 autoreply define want_ip_neighbor_events
 225 {
 226   option deprecated;
 227   u32 client_index;
 228   u32 context;
 229   bool enable;
 230   u32 pid;
 231   vl_api_address_t ip;
 232   vl_api_interface_index_t sw_if_index [default=0xffffffff];
 233 };
 234
 235 /** \brief Tell client about an IP4 ARP resolution event or
 236            MAC/IP info from ARP requests in L2 BDs
 237     @param client_index - opaque cookie to identify the sender
 238     @param pid - client pid registered to receive notification
 239     @param neighbor - new neighbor created
 240 */
 241 define ip_neighbor_event
 242 {
 243   option deprecated;
 244   u32 client_index;
 245   u32 pid;
 246   vl_api_ip_neighbor_t neighbor;
 247 };
 248
 249 service {
 250   rpc want_ip_neighbor_events returns want_ip_neighbor_events_reply
 251     events ip_neighbor_event;
 252 };
 253
 254
 255 /** \brief Register for IP neighbour events (creation or deletion)
 256     @param client_index - opaque cookie to identify the sender
 257     @param context - sender context, to match reply w/ request
 258     @param enable - 1 => register for events, 0 => cancel registration
 259     @param pid - sender's pid
 260     @param ip - exact IP address of interested neighbor resolution event
 261     @param sw_if_index - interface on which the IP address is present.
 262 */
 263 autoreply define want_ip_neighbor_events_v2
 264 {
 265   u32 client_index;
 266   u32 context;
 267   bool enable;
 268   u32 pid;
 269   vl_api_address_t ip;
 270   vl_api_interface_index_t sw_if_index [default=0xffffffff];
 271 };
 272
 273 enum ip_neighbor_event_flags
 274 {
 275  /* The neighbor has been added/learned */
 276  IP_NEIGHBOR_API_EVENT_FLAG_ADDED = 0x1,
 277  /* The neighbor has been removed/expired */
 278  IP_NEIGHBOR_API_EVENT_FLAG_REMOVED = 0x2,
 279 };
 280
 281 /** \brief Tell client about an IP4 ARP resolution event or
 282            MAC/IP info from ARP requests in L2 BDs
 283     @param client_index - opaque cookie to identify the sender
 284     @param pid - client pid registered to receive notification
 285     @param flags - Flags
 286     @param neighbor -  neighbor
 287 */
 288 define ip_neighbor_event_v2
 289 {
 290   u32 client_index;
 291   u32 pid;
 292   vl_api_ip_neighbor_event_flags_t flags;
 293   vl_api_ip_neighbor_t neighbor;
 294 };
 295
 296 service {
 297   rpc want_ip_neighbor_events_v2 returns want_ip_neighbor_events_v2_reply
 298     events ip_neighbor_event_v2;
 299 };
 300
 301 counters ip4_neighbor {
 302   throttled {
 303     severity info;
 304     type counter64;
 305     units "packets";
 306     description "ARP requests throttled";
 307   };
 308   resolved {
 309     severity info;
 310     type counter64;
 311     units "packets";
 312     description "ARP requests resolved";
 313   };
 314   no_buffers {
 315     severity error;
 316     type counter64;
 317     units "packets";
 318     description "ARP requests out of buffer";
 319   };
 320   request_sent {
 321     severity info;
 322     type counter64;
 323     units "packets";
 324     description "ARP requests sent";
 325   };
 326   non_arp_adj {
 327     severity error;
 328     type counter64;
 329     units "packets";
 330     description "ARPs to non-ARP adjacencies";
 331   };
 332   no_source_address {
 333     severity error;
 334     type counter64;
 335     units "packets";
 336     description "no source address for ARP request";
 337   };
 338 };
 339
 340 counters ip6_neighbor {
 341   throttled {
 342     severity info;
 343     type counter64;
 344     units "packets";
 345     description "throttled";
 346   };
 347   drop {
 348     severity error;
 349     type counter64;
 350     units "packets";
 351     description "address overflow drops";
 352   };
 353   request_sent {
 354     severity info;
 355     type counter64;
 356     units "packets";
 357     description "neighbor solicitations sent";
 358   };
 359   no_source_address {
 360     severity error;
 361     type counter64;
 362     units "packets";
 363     description "no source address for ND solicitation";
 364   };
 365   no_buffers {
 366     severity error;
 367     type counter64;
 368     units "packets";
 369     description "no buffers";
 370   };
 371 };
 372
 373 paths {
 374   "/err/ip4-arp" "ip4_neighbor";
 375   "/err/ip4-glean" "ip4_neighbor";
 376   "/err/ip6-arp" "ip6_neighbor";
 377   "/err/ip6-glean" "ip6_neighbor";
 378 };
 379
 380 /*
 381  * Local Variables:
 382  * eval: (c-set-style "gnu")
 383  * End:
 384  */