src/plugins/map/map_doc.rst

   1 MAP and Lw4o6
   2 =============
   3
   4 This is a memo intended to contain documentation of the VPP MAP and
   5 Lw4o6 implementations. Everything that is not directly obvious should
   6 come here.
   7
   8 MAP-E Virtual Reassembly
   9 ------------------------
  10
  11 The MAP-E implementation supports handling of IPv4 fragments as well as
  12 IPv4-in-IPv6 inner and outer fragments. This is called virtual
  13 reassembly because the fragments are not actually reassembled. Instead,
  14 some meta-data are kept about the first fragment and reused for
  15 subsequent fragments.
  16
  17 Fragment caching and handling is not always necessary. It is performed
  18 when: \* An IPv4 fragment is received and the destination IPv4 address
  19 is shared. \* An IPv6 packet is received with an inner IPv4 fragment,
  20 the IPv4 source address is shared, and ‘security-check fragments’ is on.
  21 \* An IPv6 fragment is received.
  22
  23 There are 3 dedicated nodes: \* ip4-map-reass \* ip6-map-ip4-reass \*
  24 ip6-map-ip6-reass
  25
  26 ip4-map sends all fragments to ip4-map-reass. ip6-map sends all
  27 inner-fragments to ip6-map-ip4-reass. ip6-map sends all outer-fragments
  28 to ip6-map-ip6-reass.
  29
  30 IPv4 (resp. IPv6) virtual reassembly makes use of a hash table in order
  31 to store IPv4 (resp. IPv6) reassembly structures. The hash-key is based
  32 on the IPv4-src:IPv4-dst:Frag-ID:Protocol tuple (resp.
  33 IPv6-src:IPv6-dst:Frag-ID tuple, as the protocol is IPv4-in-IPv6).
  34 Therefore, each packet reassembly makes use of exactly one reassembly
  35 structure. When such a structure is allocated, it is timestamped with
  36 the current time. Finally, those structures are capable of storing a
  37 limited number of buffer indexes.
  38
  39 An IPv4 (resp. IPv6) reassembly structure can cache up to
  40 MAP_IP4_REASS_MAX_FRAGMENTS_PER_REASSEMBLY (resp.
  41 MAP_IP6_REASS_MAX_FRAGMENTS_PER_REASSEMBLY) buffers. Buffers are cached
  42 until the first fragment is received.
  43
  44 Virtual Reassembly configuration
  45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46
  47 IPv4 and IPv6 virtual reassembly support the following configuration:
  48 map params reassembly [ip4 \| ip6] [lifetime ] [pool-size ] [buffers ]
  49 [ht-ratio ]
  50
  51 lifetime: The time in milliseconds a reassembly structure is considered
  52 valid. The longer, the more reliable is reassembly, but the more likely
  53 it is to exhaust the pool of reassembly structures. IPv4 standard
  54 suggests a lifetime of 15 seconds. IPv6 specifies a lifetime of 60
  55 seconds. Those values are not realistic for high-throughput cases.
  56
  57 buffers: The upper limit of buffers that are allowed to be cached. It
  58 can be used to protect against fragmentation attacks which would aim to
  59 exhaust the global buffers pool.
  60
  61 pool-size: The number of reassembly structures that can be allocated. As
  62 each structure can store a small fixed number of fragments, it also sets
  63 an upper-bound of ‘pool-size \*
  64 MAP_IPX_REASS_MAX_FRAGMENTS_PER_REASSEMBLY’ buffers that can be cached
  65 in total.
  66
  67 ht-ratio: The amount of buckets in the hash-table is pool-size \*
  68 ht-ratio.
  69
  70 Any time pool-size and ht-ratio is modified, the hash-table is destroyed
  71 and created again, which means all current state is lost.
  72
  73 Additional considerations
  74 ^^^^^^^^^^^^^^^^^^^^^^^^^
  75
  76 Reassembly at high rate is expensive in terms of buffers. There is a
  77 trade-off between the lifetime and number of allocated buffers. Reducing
  78 the lifetime helps, but at the cost of loosing state for fragments that
  79 are wide apart.
  80
  81 Let: R be the packet rate at which fragments are received. F be the
  82 number of fragments per packet.
  83
  84 Assuming the first fragment is always received last. We should have:
  85 buffers > lifetime \* R / F \* (F - 1) pool-size > lifetime \* R/F
  86
  87 This is a worst case. Receiving the first fragment earlier helps
  88 reducing the number of required buffers. Also, an optimization is
  89 implemented (MAP_IP6_REASS_COUNT_BYTES and MAP_IP4_REASS_COUNT_BYTES)
  90 which counts the number of transmitted bytes and remembers the total
  91 number of bytes which should be transmitted based on the last fragment,
  92 and therefore helps reducing ‘pool-size’.
  93
  94 But the formula shows that it is challenging to forward a significant
  95 amount of fragmented packets at high rates. For instance, with a
  96 lifetime of 1 second, 5Mpps packet rate would require buffering up to
  97 2.5 millions fragments.
  98
  99 If you want to do that, be prepared to configure a lot of fragments.