MAP-T and MAP-E support

Owned by Dejan Pojbič
Oct 17, 2024
11 min read

Introduction

MAP is a mechanism for transporting IPv4 packets across an IPv6 network using IP translation (MAP-T) or encapsulation (MAP-E), and a generic mechanism for mapping between IPv6 addresses and IPv4 addresses and transport layer ports.

RFCs:

The targeted SDK support is for Qualcomm SPF 11.x and Broadcom 5.04L.02p1. However, the implementation is generic enough to cover a variety of platforms providing that the platform requirements are met.

OpenSync generic implementation is supporting both MAP-T and MAP-E and is supporting multiple ways of MAP rules provisioning (via DHCPv6 options (standard method), via HTTPS API endpoint (v6plus service) or cloud-configured MAP rule).

Overview

The high level overview flow is:

  • Controller to configure MAP settings via MAP_Config.

  • Depending on MAP_Config settings: OpenSync to obtain MAP rules either from DHCPv6 or from map rules distribution server or take cloud-provisioned single MAP rule. If multiple MAP rules are provisioned, OpenSync to determine which MAP rule is the BMR for this CE according to a match with End-user IPv6 prefix. The effective BMR (and DMR) will be reported in MAP_State.

  • OpenSync: Do the MAP calculation of derived MAP parameters (most importantly: public MAP IPv4 address, MAP IPv6 address, port ranges assigned to this CE, etc) according to MAP rules (matched BMR) and End-user IPv6 prefix. If explicit port parameters (explicit PSID and PSID_len) are provisioned (via DHCPv6), take those into account. Report all the effective (either derived or explicit) MAP parameters in MAP_State.

  • OpenSync: According to MAP_Config, for MAP-T: configure MAP-T translation parameters in the underlying backend platform implementation. For MAP-E: create and configure a virtual tunnel interface according to Tunnel_Interface.

  • According to MAP configuration and effective MAP parameters reported in MAP_State Controller to further configure: a virtual tunnel interface via Tunnel_Interface (for MAP-E), assign MAP IPv4 and MAP IPv6 addresses to a MAP-E interface (Wifi_Inet_Config, IP_Interface/IPv6_Address), configure a default IPv4 route via Wifi_Route_Config, configure Netfilter (SNAT), etc.

  • Important: if a device does not get an IPv6 prefix (DHCPv6 option 26 – prefix delegated), MAP cannot be provisioned and MAP_Config should not be configured. DHCPv6 options received are reported by OpenSync in the DHCP_Option table.

  • Note: MAP-T and MAP-E RFCs consistently use the term end-user IPv6 prefix, thus we use the same term throughout this document. In practice, end-user IPv6 prefix is usually the delegated IPv6 prefix (DHCPv6 option 26).

Further details are defined in the remaining of the document.

Cloud interaction

  • Via new OVSDB tables: MAP_Config, MAP_State

  • Via other existing tables: DHCP_Option, Wifi_Route_Config, Netfilter, Wifi_Inet_Config, Tunnel_Interface IP_Interface, IPv6_Address, and others.

Northbound API

OVSDB schema

MAP_Config

Name

Type

Description

Name

Type

Description

map_type

enum

MAP type: MAP-T or MAP-E

{ "map-t", "map-e" }

map_rules_dhcp

bool

(MAP-E: DHCPv6 option 94, MAP-T: DHCPv6 option 95)

If this flag is set to true then for:

  • MAP-T: OpenSync will configure MAP translation parameters obtained from DHCPv6 on the underlying MAP-T implementation (e.g. nat46). Effective MAP rules parameters are reported in MAP_State.

  • MAP-E: Effective MAP rules parameters are reported in MAP_State.

Note: It is a requirement of this feature for the OpenSync DHCPv6 client implementation to request options 94, 95 and report them in DHCP_Option table. The first part is already true: The OpenSync odhcp6c target layer is implemented in such a way that it always runs the odhcp6c client in a way where it requests a handful of DHCPv6 options by default (including options 94 and 95). If the DHCPv6 server is configured to include them in a reply, then they are received. A few additional fixes will be added to actually report MAP rules received in the DHCP_Option table. Note also: DHCPv6_Client for the WAN is only configured/managed by OpenSync (WANO, CM), not by the controller.

map_rules_v6plus_url

string
[optional]

If this is set, MAP rules are expected to be provisioned from a “v6plus” MAP rules distribution server. In this case this field configures the URL of the HTTPS API endpoint.

BMR_IPv6_prefix

string
[optional]

Cloud-provisioned Basic Mapping Rule (BMR) IPv6 prefix.

Configured static BMR rule IPv6 prefix setting if neither map_rules_dhcp nor map_rules_v6plus_url is set.

BMR_IPv4_prefix

string
[optional]

Cloud-provisioned Basic Mapping Rule (BMR) IPv4 prefix.

Configured static BMR rule IPv4 prefix setting if neither map_rules_dhcp nor map_rules_v6plus_url is set.

BMR_ea_len

integer
[optional]

Cloud-provisioned Basic Mapping Rule (BMR)’s EA-bits length.

Configured static BMR rule’s EA-bits length setting if neither map_rules_dhcp nor map_rules_v6plus_url is set.

BMR_psid_offset

integer
[optional]

Cloud-provisioned Basic Mapping Rule (BMR) PSID offset.

Configured static BMR rule’s PSID offset setting if neither map_rules_dhcp nor map_rules_v6plus_url is set.

DMR

string
[optional]

Cloud-provisioned Default Mapping Rule (DMR) setting.

Configured static DMR setting if neither map_rules_dhcp nor map_rules_v6plus_url is set.

The IPv6 address of the BR (MAP-E) or DMR prefix (MAP-T).

if_name

string

[immutable, unique]

MAP interface name.

e.g.: wan6_map or something similar.

In case of MAP-T a control interface with this name configured here will be created by the underying platform MAP-T implementation (e.g. nat46 kernel module).

Note: In case of MAP-E a dedicated tunnel interface is needed and a tunnel interface with this name would be created via a separate (existing) OVSDB table Tunnel_Interface.

In case of MAP-E: The controller is expected to assign the calculated public IPv4 address and calculated IPv6 addresses (both reported in MAP_State) to the MAP interface (via standard ways: Wifi_Inet_Config, IPv6_Address/IP_Interface, etc).

map_legacy_draft3

bool
[optional]

Use MAP legacy RFC draft 03 to calculate MAP IPv6 address (it’s interface-identifier part).

The default is unset/false.

Some providers seem to still use the legacy MAP RFC draft 03.

other_config

map (key:value)
[optional]

Reserved for future use if we may need to add any obscure or rarely used settings that may fit to the “other_config” concept.

Currently no configuration (no keys) defined here.

Notes on MAP_Config:

  • For the MAP configuration to be valid only 1 (and exactly 1) of MAP rules provisioning methods must be configured: so either map_rules_dhcp, map_rules_v6plus_url, or cloud pushed (single) MAP rule (BMR_IPv6_prefix, BMR_IPv4_prefix, BMR_ea_length, BMR_psid_offset, DMR).

Notes:

  • More then one MAP rule may be provisioned via DHCP options or via map rules distribution server. In that case OpenSync will determine which of the FMRs is a BMR for this MAP domain and set MAP_State accordingly. BMR rule is determined by a match of the Rule-IPv6-prefix against the End-user IPv6 prefix. The MAP rule that matches will then be reported in MAP_State as the effective BMR (along with DMR).

  • It is an error if none of the MAP rules matches the End-user IPv6 prefix (usually IA_PD) in this case the effective BMR_* and DMR parameters in MAP_State will be left unset. If these fields are not set MAP bringup should be considured unsuccessful.

MAP_State

Name

Type

Description

Name

Type

Description

map_type

enum

MAP type: MAP-T or MAP-E

{ map-t, map-e }

map_rules_dhcp

bool

MAP rules config provisioned from DHCPv6.

map_rules_v6plus_url

string
[optional]

“v6plus” MAP rules server URL set if MAP rules config was provisioned from MAP rule distribution server.

BMR_IPv6_prefix

string
[optional]

Effective Basic Mapping Rule (BMR) IPv6 prefix.

BMR_IPv4_prefix

string
[optional]

Effective Basic Mapping Rule (BMR) IPv4 prefix.

BMR_ea_len

integer
[optional]

Effective Basic Mapping Rule (BMR) EA-bits length.

BMR_psid_offset

integer
[optional]

Effective Basic Mapping Rule (BMR) PSID offset.

Obtained from MAP rules or explicitly provisioned from DHCPv6 MAP Port Parameters option.

DMR

string

Effective Default Mapping Rule (DMR).

The IPv6 address of the BR (MAP-E) or DMR prefix (MAP-T).

if_name

string

[unique]

MAP interface name.

map_legacy_draft3

bool
[optional]

True if MAP legacy RFC draft 03 way of calculating MAP IPv6 address (it’s interface-identifier part) was configured.

psid

integer

Effective PSID (Port Set Identifier).

  • Either calculated from MAP rules parameters and End-user IPv6 prefix or an explicit PSID value provisioned from DHCPv6 MAP Port Parameters option.

psid_len

integer

Effective PSID length.

  • Either calculated from MAP rules parameters and End-user IPv6 prefix or an explicit PSID length value provisioned from DHCPv6 MAP Port Parameters option.

map_ipv4_addr

string

Effective calculated MAP IPv4 address.

In most real use-case scenarios this would be a public IPv4 address.

CE IPv4 address calculated according to MAP rules and End-user IPv6 prefix.

It would then be assigned (by the controller) to the MAP interface (functionality-wise this may not be strictly neccessary in some configurations).

map_ipv6_addr

string

Effective calculated MAP IPv6 address.

CE IPv6 address calculated according to MAP rules and End-user IPv6 prefix.

It would then be assigned (by the controller) to the MAP interface

port_sets

 

string

Effective calculated port range sets for this CE.

In the simplest case, where the BMR_psid_offset=0, there’s only 1 port range e.g.: “55296-57343”.

For nonzero psid offset, we have more than 1 port range in the port range set for a given CE e.g.: “30208-30719, 46592-47103, 62976-63487”

Given the effective port range sets and public IPv4 address for this CE Controller would then configure Netfilter (SNAT, etc).

Tunnel_Interface

This is an existing OVSDB table introduced with OpenSync 4.4 for the IPSec feature. For the purpose of MAP-E we will extend it to support ip6tnl.

Fields added or extended:

  • if_type (existing field, enum added)

  • mode (NEW)

  • status (NEW)

In the table bellow all the existing and new fields are presented along with specific MAP-E configuration notes.

Name

Type

Description

Name

Type

Description

if_name

string

[immutable]

Name for this tunnel interface.

if_type

enum

Type of this tunnel interface.

ADD type "ip6tnl": Virtual tunnel interface IPv4|IPv6 over IPv6.

{"vti", "vti6"} -> {"vti", "vti6", "ip6tnl"}

mode

enum
[optional]

{"ipip6", ip6ip6, any}

ip6tnl supports modes ip6ip6, ipip6, any.  Mode ipip6 is IPv4 over IPv6, and mode ip6ip6 is IPv6 over IPv6, and mode any supports both IPv4/IPv6 over IPv6.

For MAP-E: mode ipip6 or mode any can be configured.

enable

bool

Enable this tunnel interface.

Until enabled, no attempt to actually create the interface will be made.

If disabled, the tunnel interface will be removed from the system.

local_endpoint_addr

string

Local endpoint of the tunnel (IPv6 address).

For MAP-E this would be set to the calculated MAP IPv6 Address (MAP_State.map_ipv6_addr). Note: this is the local endpoint address of the tunnel; the same address would also usually be assigned to the interface itself (via IP_Interface/IPv6_Address).

remote_endpoint_addr

string

Remote endpoint of the tunnel: IPv6 address.

For MAP-E this would be set to the DMR IPv6 address i.e. IPv6 address of the BR (MAP_State.DMR)

dev_if_name

string

Underlying physical interface.

Set to the effective physical WAN interface name (e.g. eth0 or eth1).

status

enum
[optional]

Status of this interface.

{"disabled", "enabled", "error"}

“enabled": The tunnel interface created successfully.

“error": The tunnel interface enabled but there was an error creating it.

Note: The virtual tunnel interface is created only. As usual, the reponsibility of bringing the interface up is covered by NM/Wifi_Inet_Config. To actually bring the interface UP, a Wifi_Inet_Config row for this interface name is needed (network:=true).

 

Southbound API

  • MAP-T: OSN MAP-T API: osn_mapt: OpenSync already has an OSN MAP-T API: osn_mapt (and an ivictl/cernet backend implementation). The API was introduced by OpenSync 2.2 implementation of MAP-T. However, the API does not have a generic signature we would like: the API and parameters follow some aspects of the ivictl/cernet backend implementation. We would like a generic API with parameters following generic MAP concepts as defined by RFCs, not derived values such as public IPv4 address or parameters fitting to specific backend implementations. A generic API to be introduced. The purpose of this API is to configure (via the underlying backend implementation, e.g. nat46) MAP-T translation parameters in the kernel.

  • MAP-E: OSN Tunnel Interface API: osn_tunnel_iface: This is an existing OpenSync OSN API introduced in OpenSync 4.4 for the IPSec feature to support virtual tunnel interfaces. In contrast to MAP-T, the MAP-E mechanism is encapsulation i.e. tunneling; for MAP-E we need to extend the osn_tunnel_iface API (and the backend implementation) to add support for ip6tnl virtual tunnel interfaces.

Platform requirements

OpenSync reference platform requirements

  • MAP-E: support for IPv6 tunnels: CONFIG_IPV6_TUNNEL

  • MAP implementation: nat46: Generic stateless NAT46 kernel module for Linux

    • There are a few MAP implementations available, but only some of them are suitable or even maintained. (A short summary of different implementations bellow)

    • For OpenSync generic MAP support the reference chosen underlying backend for configuring MAP-T parameters will be nat46: Generic stateless NAT46 kernel module for Linux: https://github.com/ayourtch/nat46/

      • This implementation seems to be one of the rare implementations that has been more widely accepted by community/vendors and is maintained. It is used by OpenWRT, Broadcom 5.04L.02p1 started to include it (not enabled by default). QSDK 5.3 and QSDK 11.x have nat46 packages available in SDK. Broadcom 5.02L.07 does not include it, we would need to manually add it to the image.

      • Note: On OpenWrt platforms nat46.ko implementation is usually accompanied with OpenWRT package MAP (https://openwrt.org/packages/pkgdata/map) that includes /lib/netifd/proto/map.sh, a script to configure MAP-T or MAP-E with simple configs via netifd + mapcalc (MAP parameter calculation tool).

    • The OSN southbound API will be made as generic as possible providing possibility to quickly add backend support for an additional different MAP implementation, if required.

OpenSync requirements

  • VPNM (VPNM manager) enabled (and osn_tunnel_iface it depends on). VPNM/osn_tunnel_iface was introduced with OpenSync 4.4. With OpenSync 5.6 we’re extending it to support ipip6 tunnels.

Implementation notes

  • No need for a new manager.

  • A new module will be added to NM2. The module will handle the newly introduced MAP_Config and MAP_State. Dispatching the work to further submodules in OpenSync lib. The main OpenSync MAP-related tasks will cover:

    • Depending on MAP_Config settings: obtain MAP rules either from DHCPv6 or from map rules distribution server or take the cloud-configured MAP rule.

    • If multiple MAP rules are provisioned (FMR table), determine and select the BMR rule according to a match of a Rule-IPv6-prefix against the End-user IPv6 Prefix.

    • Do the MAP calculation of derived MAP parameters (public IPv4 address, psid, port ranges, etc) according to MAP rule and End-user IPv6 prefix. Report all the effective MAP parameters in MAP_State.

    • Configure MAP-T translation parameters in the underlying backend platform implementation.

    • Create and configure a virtual tunnel interface needed for MAP-E.

  • Some existing OSN APIs and backend implementations to be extended, such as OSN tunnel interface API/backend: to support IPv6 tunnels.

  • OpenSync will support only the CE role. It does not make much sense to support the BR role. Hence in the case where multiple (more then one) MAP rules are provisioned (either via DHCPv6 or via MAP rule distribution server) i.e. a FMR table then the FMR rules will not be handled: In a FMR table only max 1 rule is a BMR rule i.e. a MAP rule for this specific CE (actually for this MAP Domain) (determined by a match of a MAP rule’s IPv6 prefix against the End-user IPv6 Prefix). Technically by the spec, though, a CE could have a FMR table as well and use FMRs for direct communication to other CEs without having to use the BR as a middleman.

  • The method of distributing MAP rules and parameters via MAP rule distribution server is not a mechanism defined by any standard or RFC. Although RFCs do define one standard possible way of MAP rules distribution, that is via DHCPv6, this is only one possible way, the spec is open for MAP rules to be provisioned any other way, even statically (e.g. static controller-pushed config) or for instance via a MAP rule distribution server such as it is the case with the “IPv6 plus” service. OpenSync to provide a hopefully generic API for the MAP rule distribution server option and an implementation of this API for the specific “IPv6 plus” service.

Examples of OVSDB configuration

Example MAP_Config and MAP_State:

root@opensync:~# ovsh s MAP_Config ----------------------------------- BMR_IPv4_prefix | ["set",[]] | BMR_IPv6_prefix | ["set",[]] | BMR_ea_len | ["set",[]] | BMR_psid_offset | ["set",[]] | DMR | ["set",[]] | _uuid | e3b3~6a01 | _version | 71bb~7e8c | if_name | wan6_map | map_rules_dhcp | true | map_rules_v6plus_url | ["set",[]] | map_type | map-t | ----------------------------------- root@opensync:~# ovsh s MAP_State ------------------------------------------------------------------------------------------------- BMR_IPv4_prefix | 192.0.2.0/24 | BMR_IPv6_prefix | 2001:ee2:1704::/48 | BMR_ea_len | 16 | BMR_psid_offset | 4 | DMR | 64:ff9b::/64 | _uuid | 9019~011c | _version | df7e~1abe | if_name | wan6_map | map_ipv4_addr | 192.0.2.153 | map_ipv6_addr | 2001:ee2:1704:99ff:0:c000:299:ff | map_rules_dhcp | true | map_rules_v6plus_url | ["set",[]] | map_type | map-t | port_sets | 8176-8191,12272-12287,16368-16383,20464-20479,24560-24575,28656-28671, | : 32752-32767,36848-36863,40944-40959,45040-45055,49136-49151,53232-53247, : : 57328-57343,61424-61439,65520-65535 : psid | 255 | psid_len | 8 | -------------------------------------------------------------------------------------------------