src/vnet/ip/punt.md

   1 .. _punt:
   2
   3 Punting Packets
   4 ===============
   5
   6 .. toctree::
   7
   8 Overview
   9 ________
  10
  11 To 'punt' can mean different things to different people. In VPP the
  12 data-plane punts when a packet cannot be handled by any further
  13 nodes. Punt differs from drop, in that VPP is giving other elements of
  14 the system the opportunity to handle this packet.
  15
  16 A popular meaning of punt is to send packets to the user/control-plane.
  17 This is specific option of the more general case above, where VPP is
  18 handing the packet to the control-plane for further prosessing.
  19
  20 The Punt Infrastructe
  21 ---------------------
  22
  23 Exception packets are those that a given node cannot handle via normal
  24 mecahnisms.
  25 Punting of exception packets is handled via the VLIB 'punt
  26 infra'. There are two types of nodes; sources and sinks. Sources
  27 allocate a punt 'reason' from the infrastructre and load time. When
  28 they encouter an exception during switch time it will tag the packet
  29 with the reason and ship the packet of the the punt-dispatch node. A
  30 sink will register with the punt infra at load time so it can receive
  31 packets that were punted for that reason. If no sinks are registerd
  32 for a given reason the packet is dropped, if multiple sinks register
  33 the packets are replicated.
  34
  35 This mechanism allows us to extend the system to deal with packets
  36 that the source node would otherise drop.
  37
  38
  39 Punting to the Control Plane
  40 ----------------------------
  41
  42 Active Punt
  43 -----------
  44
  45 The user/control-plane specifies that this is the type of packet I
  46 want to receive and this is where I want it sent.
  47
  48 Currently there exists 3 ways to describe how to match/classify the
  49 packets to be punted:
  50 ...
  51  1) a matching UDP port
  52  2) a matching IP protocol (i.e. OSPF)
  53  3) a matching punt excpetion reason (see above)
  54 ...
  55
  56 Depending on the type/classification of the packet to be punted, that
  57 active punt will register itself into the VLIB graph to receive those
  58 packets. For example, if it's a packet matching a UDP port then it
  59 will hook into the UDP port dispatch functions; udp_register_port().
  60
  61 There exists only one sink for passive punt, a unix domain socket. But
  62 more work is underway in this area.
  63
  64 see the API in: vnet/ip/punt.api
  65
  66
  67
  68 Passive Punt
  69 ------------
  70
  71 VPP input packet processing can be described as a series of
  72 classifiers. For example, a sequence of input classifications could
  73 be, is it IP? is it for-us? is it UDP? is it a known UDP-port? If at
  74 some point in this pipline VPP has no further classifications to make,
  75 then the packet can be punted, which means sent to ipX-punt node. This
  76 is described as passive since the control-plane is thus receiving
  77 every packet that VPP does not itself handle.
  78 For passive punt the user can specify where the packets should be
  79 sent and whether/how they should be policed/rate-limited.
  80
  81 see the API in: vnet/ip/ip.api
  82