View source for VPP/Configure an LW46 (MAP-E) Terminator

This example use case shows how to configure a Mapping of Address and Port (MAP) set of features to create an algorithmic mapping between IPv6 end-user prefixes and IPv4 addresses and ports. 

__TOC__

== Introduction ==

The MAP set of features implements MAP-E ([https://tools.ietf.org/html/rfc7597 RFC7597]), MAP-T ([https://tools.ietf.org/html/rfc7599 RFC7599]), LW4o6 ([https://tools.ietf.org/html/rfc7596 RFC7596])
and SIIT-DC ([https://tools.ietf.org/html/rfc7755 RFC7755]). In addition, IPv6 as a service through the 6RD mechanism ([https://tools.ietf.org/html/rfc5969 RFC5969]) is
supported.

All these solutions have many similarities, supporting carrying IPv4 over IPv6 tunnels, or
translating IPv4 to IPv6. They are largely based on the A+P architecture ([https://tools.ietf.org/html/rfc6346 RFC6346]?) where
multiple end-users are assigned the same IPv4 address and different sets of transport layer ports. IPv4 address sharing restricts the transport layer protocols to TCP, UDP and ICMP. To
accommodate end-users needing support for other transport protocols, these mechanisms also
support carrying full IPv4 addresses or even IPv4 prefixes.

The main reason these solutions are developed is to share IPv4 addresses among multiple end users, with state being kept as close to the end-user as possible. This VPP feature implements the network side function (AFTR/BR) which are stateless and therefore easy to scale.

== Mechanism in a nutshell ==

=== MAP-E ===

MAP-E is a method of IPv4 in IPv6 tunneling (RFC2473), supporting algorithmic mapping between IPv6 end-user prefixes and IPv4 addresses and ports. The end user, given a few provisioned parameters can from the assigned IPv6 prefix deduce its IPv4 address and port-set. Algorithmic mapping means the service provider can have a handful of simple rules determining how blocks of IPv6 prefixes are mapped into blocks of IPv4 addresses and ports.

For example:

  map add domain ip4-pfx 20.0.0.0/20
  ip6-pfx 2001:db8::/32
  ip6-src 2001:db9::1
  ea-bits-len 18
  psid-offset 6 psid-len 6

The above mapping uses 16 bits (ea-bits-len) of the IPv6 prefix for the end-users IPv4 address and port-set ID. This single mapping rule supports with a block of 4096 IPv4 addresses and a sharing ratio of 64, 262144 end-users.

=== Lightweight 4over6 ===

LW4o6 is a subset of MAP-E, with per-subscriber rules. It uses the same tunneling mechanism
and configuration as MAP-E. It does not use embedded address bits.

For example:

  map add domain ip4-pfx 20.0.0.0/32 ip6-pfx ::/0 ip6-src 2001:db9::1
  ea-bits-len 0 psid-offset 6 psid-len 6
  map add rule ip4-pfx 20.0.0.0/32 psid 0 ip6-dst 2001:db8::1
  map add rule ip4-pfx 20.0.0.1/32 psid 1 ip6-dst 2001:db8::2


The example mapping above assigns PSID #0 to the end-user with IPv6 address 2001:db8::1 and assigns PSID #1 to the end user with IPv6 address 2001:db8::2.

=== MAP-T ===

MAP-T supports the same features as MAP-E, but uses translation instead of encapsulation. The
end user configures its IPv4 address and port-range, and the end-users CE translates the IPv4
packets into IPv6 packets, and the MAP BR (VPP) translates those back from IPv6 to IPv4. This is known as double translation.

=== SIIT-DC ===

SIIT-DC is a mechanism that uses MAP-T but only in single translation mode. It allows customers to operate IPv6 only data-centers with a stateless or per-subscriber function translating between public IPv4 addresses and ports to the IPv6 addresses of the servers used in the DC.

=== 6RD ===

6RD is a mechanism doing the inverse of MAP. It encapsulates IPv6 packets in IPv4, and uses an
algorithmic mapping allowing end-users given an IPv4 address and some configuration parameters
to deduce their IPv6 end-user prefix.

== VPP CLI ==

=== Configuration ===

<pre>
map add domain ip4-pfx <ip4-pfx> ip6-pfx <ip6-pfx> ip6-src <ip6-pfx>
                 ea-bits-len <n> psid-offset <n> psid-len <n>
                 [map-t] [mtu <mtu>]
map add rule index <domain> psid <psid> ip6-dst <ip6-addr>
map del domain indexk <domain>
map params reassembly [ip4 | ip6] [lifetime <lifetime-ms>]
                      [pool-size <pool-size>] [buffers <buffers>]
                      [ht-ratio <ht-ratio>]
map params traffic-class {0x00-0xFF | copy }
map params pre-resolve {ip4-nh <address>} | {ip6-nh <address>}
map params security-check on | off
map params security-check fragments on | off
map params icmp-source-address <ip4-address>

sixrd add domain ip6-pfx <ip6-pfx> ip4-pfx <ip4-pfx>
                 ip4-src <ip4-addr>
sixrd del domain index <domain>
</pre>


=== Show commands === 

The following example lists VPP <tt>show</tt> commands that are useful for seeing information related to a map-e configuration.

  show map domain
  show map stats
  show map fragments
  show sixrd domain
  show sixrd stats


== VPP API ==

==== Example: Add MAP Domain ====

The following code snippet shows an example of a data structure that can be used to add a MAP domain.

<pre>
/** \brief Add MAP domains
@param client_index - opaque cookie to identify the sender
@param context - sender context, to match reply w/ request
@param ip6_prefix - Rule IPv6 prefix
@param ip4_prefix - Rule IPv4 prefix
@param ip6_src - MAP domain IPv6 BR address / Tunnel source
@param ip6_prefix_len - Rule IPv6 prefix length
@param ip4_prefix_len - Rule IPv4 prefix length
@param ea_bits_len - Embedded Address bits length
@param psid_offset - Port Set Identifider (PSID) offset
@param psid_length - PSID length
@param is_translation - MAP-E / MAP-T
@param mtu - MTU
*/
define map_add_domain {
u32 client_index;
u32 context;
u8 ip6_prefix[16];
u8 ip4_prefix[4];
u8 ip6_src[16];
u8 ip6_prefix_len;
u8 ip4_prefix_len;
u8 ip6_src_prefix_len;
u8 ea_bits_len;
u8 psid_offset;
u8 psid_length;
u8 is_translation;
u16 mtu;
};
</pre>


The following code snippet shows an example of a data structure that can be used as a reply to a call to add a MAP domain. 

<pre>
/** \brief Reply for MAP domain add
@param context - returned sender context, to match reply w/ request
@param index - MAP domain index
@param retval - return code
*/
define map_add_domain_reply {
u32 context;
u32 index;
i32 retval;
};
</pre>


==== Example: Delete MAP Domain ====

The following code snippet shows an example of a data structure that can be used to delete a MAP domain.

<pre>
/** \brief Delete MAP domain
@param client_index - opaque cookie to identify the sender
@param context - sender context, to match reply w/ request
@param index - MAP Domain index
*/
define map_del_domain {
u32 client_index;
u32 context;
u32 index;
};
</pre>

The following code snippet shows an example of a data structure that can be used as a reply to a call to delete a MAP domain.

<pre>
/** \brief Reply for MAP domain del
  @param context - returned sender context, to match reply w/ request
  @param retval - return code
*/
define map_del_domain_reply {
  u32 context;
  i32 retval;
};
</pre>


==== Example: MAP Rules And Domain Query ====

The following examples show data structures and definitions that can be used to manage MAP rules.

<pre>
/** \brief Add or Delete MAP rule from a domain (Only used for shared IPv4 per subscriber)
  @param client_index - opaque cookie to identify the sender
  @param context - sender context, to match reply w/ request
  @param index - MAP Domain index
  @param is_add - If 1 add rule, if 0 delete rule
  @param ip6_dst - MAP CE IPv6 address
  @param psid - Rule PSID
*/
define map_add_del_rule {
  u32 client_index;
  u32 context;
  u32 index;
  u32 is_add;
  u8 ip6_dst[16];
  u16 psid;
};
</pre>

<pre>
/** \brief Reply for MAP rule add/del
  @param context - returned sender context, to match reply w/ request
  @param retval - return code
*/
define map_add_del_rule_reply {
  u32 context;
  i32 retval;
};
</pre>


<pre>
/** \brief Get list of map domains
  @param client_index - opaque cookie to identify the sender
*/
define map_domain_dump {
  u32 client_index;
  u32 context;
};
</pre>


<pre>
manual_java define map_domain_details {
  u32 domain_index;
  u8 ip6_prefix[16];
  u8 ip4_prefix[4];
  u8 ip6_src[16];
  u8 ip6_prefix_len;
  u8 ip4_prefix_len;
  u8 ip6_src_len;
  u8 ea_bits_len;
  u8 psid_offset;
  u8 psid_length;
  u8 flags;
  u16 mtu;
  u8 is_translation;
};

define map_rule_dump {
  u32 client_index;
  u32 context;
  u32 domain_index;
};
</pre>

<pre>
manual_java define map_rule_details {
  u8 ip6_dst[16];
  u16 psid;
};
/** \brief Request for a single block of summary stats
@param client_index - opaque cookie to identify the sender
@param context - sender context, to match reply w/ request
*/
define map_summary_stats {
  u32 client_index;
  u32 context;
};
</pre>

<pre>
/** \brief Reply for map_summary_stats request
  @param context - sender context, to match reply w/ request
  @param retval - return code for request
  @param total_bindings -
  @param total_pkts -
  @param total_ip4_fragments -
  @param total_security_check -
*/
define map_summary_stats_reply {
  u32 context;
  i32 retval;
  u64 total_bindings;
  u64 total_pkts[2];
  u64 total_bytes[2];
  u64 total_ip4_fragments;
  u64 total_security_check[2];
};
</pre>

== Architecture ==

You can find the code for the MAP implementation in the <tt>[install_dir]/vnet/map/</tt> directory.

=== Packet Flow === 

The following figure shows the packet flow in the MAP domain.

[[file:VPP use of MAP-E data-structure.jpg|The packet flow in a MAP-E configuration.]]

=== Node Graphs ===

The following figures show the node graphs used in this example implementation of a MAP domain.

[[File:VPP MAP-E node-graph for ipv6 lookup.jpg|The node graph used by a MAP-E configuration for IPv6 lookup.]]

[[File:VPP MAP-E node-graph ipv4 lookup.jpg|The node graph used by a MAP-E configuration for IPv4 lookup.]]