# cernet/map architecture

> Architecture diagram of the GitHub repository cernet/map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cernet/map
- Repository: https://github.com/cernet/map

## Overview

MAP is a Linux/OpenWrt customer-edge implementation that carries IPv4 traffic over IPv6 using MAP-T translation or MAP-E encapsulation, with optional NAT44. The principal workflow is operator configuration followed by IPv4/IPv6 packet interception, address/rule mapping, transport-port handling, and transmission in the opposite protocol family. The graph reflects the sampled controller, ioctl, hook, mapping, and transmission code; README-described compatibility modes are retained as capabilities, but their internal implementation paths are not inferred.

Main entry points: [`modules/ivi_xmit.c`](https://github.com/cernet/map/blob/master/modules/ivi_xmit.c) (Packet conversion), [`modules/ivi_nf.c`](https://github.com/cernet/map/blob/master/modules/ivi_nf.c) (Netfilter hooks), [`modules/ivi_ioctl.c`](https://github.com/cernet/map/blob/master/modules/ivi_ioctl.c) (Config interface), [`utils/ivictl.c`](https://github.com/cernet/map/blob/master/utils/ivictl.c) (ivictl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_examples["Mode examples"]
  node_controller["ivictl<br/>[ivictl.c]"]
  node_device["Config interface<br/>[ivi_ioctl.c]"]
  node_module["Module lifecycle<br/>[ivi_module.c]"]
end

subgraph group_packet["Packet processing"]
  node_hooks["Netfilter hooks<br/>[ivi_nf.c]"]
  node_transmit["Packet conversion<br/>[ivi_xmit.c]"]
end

subgraph group_mapping["Mapping state"]
  node_rules4[("IPv4 rule trie<br/>[ivi_rule.c]")]
  node_rules6[("IPv6 rule radix<br/>[ivi_rule6.c]")]
  node_mapstate[("UDP/ICMP mappings<br/>[ivi_map.c]")]
  node_tcpstate[("TCP mappings<br/>[ivi_map_tcp.c]")]
end

subgraph group_external["Networks"]
  node_private4(("Private IPv4 network"))
  node_ipv6net(("IPv6 domain"))
  node_public4(("Public IPv4 network"))
  node_othermodes["Compatibility modes"]
end

node_operator(("CPE operator"))

node_operator -->|"selects mode"| node_examples
node_examples -.->|"configure"| node_controller
node_operator -->|"sets parameters"| node_controller
node_controller -->|"issues ioctls"| node_device
node_device -->|"inserts rules"| node_rules4
node_device -->|"inserts rules"| node_rules6
node_module -->|"registers hooks"| node_hooks
node_private4 -->|"sends IPv4"| node_hooks
node_ipv6net -->|"sends IPv6"| node_hooks
node_hooks -->|"dispatches packets"| node_transmit
node_transmit -->|"looks up IPv4"| node_rules4
node_transmit -->|"looks up IPv6"| node_rules6
node_transmit -->|"maps UDP/ICMP ports"| node_mapstate
node_transmit -->|"maps TCP ports"| node_tcpstate
node_transmit -->|"emits MAP-E/T"| node_ipv6net
node_transmit -->|"emits IPv4"| node_public4
node_othermodes -.->|"supports"| node_operator

click node_examples "https://github.com/cernet/map/blob/master/zyhgw-T44"
click node_controller "https://github.com/cernet/map/blob/master/utils/ivictl.c"
click node_device "https://github.com/cernet/map/blob/master/modules/ivi_ioctl.c"
click node_module "https://github.com/cernet/map/blob/master/modules/ivi_module.c"
click node_hooks "https://github.com/cernet/map/blob/master/modules/ivi_nf.c"
click node_transmit "https://github.com/cernet/map/blob/master/modules/ivi_xmit.c"
click node_rules4 "https://github.com/cernet/map/blob/master/modules/ivi_rule.c"
click node_rules6 "https://github.com/cernet/map/blob/master/modules/ivi_rule6.c"
click node_mapstate "https://github.com/cernet/map/blob/master/modules/ivi_map.c"
click node_tcpstate "https://github.com/cernet/map/blob/master/modules/ivi_map_tcp.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_examples,node_controller,node_device,node_module toneBlue
class node_hooks,node_transmit toneAmber
class node_rules4,node_rules6,node_mapstate,node_tcpstate toneMint
class node_private4,node_ipv6net,node_public4,node_othermodes toneRose
class node_operator toneIndigo
```

## Components

### Configuration

- [Mode examples](https://github.com/cernet/map/blob/master/zyhgw-T44): `zyhgw-T44`
- [ivictl](https://github.com/cernet/map/blob/master/utils/ivictl.c): `utils/ivictl.c`
- [Config interface](https://github.com/cernet/map/blob/master/modules/ivi_ioctl.c): `modules/ivi_ioctl.c`
- [Module lifecycle](https://github.com/cernet/map/blob/master/modules/ivi_module.c): `modules/ivi_module.c`

### Packet processing

- [Netfilter hooks](https://github.com/cernet/map/blob/master/modules/ivi_nf.c): `modules/ivi_nf.c`
- [Packet conversion](https://github.com/cernet/map/blob/master/modules/ivi_xmit.c): `modules/ivi_xmit.c`

### Mapping state

- [IPv4 rule trie](https://github.com/cernet/map/blob/master/modules/ivi_rule.c): `modules/ivi_rule.c`
- [IPv6 rule radix](https://github.com/cernet/map/blob/master/modules/ivi_rule6.c): `modules/ivi_rule6.c`
- [UDP/ICMP mappings](https://github.com/cernet/map/blob/master/modules/ivi_map.c): `modules/ivi_map.c`
- [TCP mappings](https://github.com/cernet/map/blob/master/modules/ivi_map_tcp.c): `modules/ivi_map_tcp.c`

### Networks

- **Private IPv4 network**
- **IPv6 domain**
- **Public IPv4 network**
- **Compatibility modes**

### Other components

- **CPE operator**

## Connections

- CPE operator → Mode examples: selects mode
- Mode examples → ivictl: configure
- CPE operator → ivictl: sets parameters
- ivictl → Config interface: issues ioctls
- Config interface → IPv4 rule trie: inserts rules
- Config interface → IPv6 rule radix: inserts rules
- Module lifecycle → Netfilter hooks: registers hooks
- Private IPv4 network → Netfilter hooks: sends IPv4
- IPv6 domain → Netfilter hooks: sends IPv6
- Netfilter hooks → Packet conversion: dispatches packets
- Packet conversion → IPv4 rule trie: looks up IPv4
- Packet conversion → IPv6 rule radix: looks up IPv6
- Packet conversion → UDP/ICMP mappings: maps UDP/ICMP ports
- Packet conversion → TCP mappings: maps TCP ports
- Packet conversion → IPv6 domain: emits MAP-E/T
- Packet conversion → Public IPv4 network: emits IPv4
- Compatibility modes → CPE operator: supports