# openthread/tayga architecture

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

- Interactive diagram: https://gitdiagram.com/openthread/tayga
- Repository: https://github.com/openthread/tayga

## Overview

##### Main components
a. TAYGA Daemon
– The user-space process (tayga.c / tayga.h)
– Implements stateless NAT64 translation logic
b. TUN Virtual Network Interface
– Created by “tayga --mktun”
– Exposes a /dev/net/tun device to the kernel
c. Kernel Networking Stack
– IPv4 stack on one side
– IPv6 stack on the other
– Routes packets to/from the TUN interface
d. Configuration and Mapping Store
– tayga.conf (static prefix, pools, addresses)
– dynamic.map file (persistent dynamic IPv6↔IPv4 assignments)
e. External Networks
– Upstream IPv6 network (clients or the Internet)
– Upstream IPv4 network (clients or the Internet)
f. Optional Firewall / iptables
– ip6tables rules controlling NAT64 prefix access
– iptables MASQUERADE for combining stateful NAT4 if needed

##### Relationships & data-flow
- IPv6 Network → Kernel IPv6 Stack → TUN Interface → TAYGA Daemon
- TAYGA Daemon → TUN Interface → Kernel IPv4 Stack → IPv4 Network
– Within the TAYGA daemon:
- Packet arrives on TUN
- Addresses looked up/translated using:
– Static mapping (RFC 6052 prefix)
– Dynamic mapping (pool + dynamic.map on disk)
- Header rewritten; forwarded back to TUN

##### Architectural patterns & design principles
– Stateless translation: no per-flow state held in RAM
– 1:1 address substitution (RFC 6052 embedding IPv4 in IPv6)
– Separation of concerns:
- TAYGA handles translation only
- Kernel handles routing & queuing
- External tools (iptables) handle firewalling / stateful NAT

##### Technologies & files
– Language: C (addrmap.c, nat64.c, dynamic.c, conffile.c)
– Build system: Autoconf/Automake (configure.ac, Makefile.am)
– Config parser: conffile.c / config.h.in
– Mapping logic: addrmap.c + dynamic.c
– TUN driver interaction: tayga.c uses /dev/net/tun
– Persistence: dynamic.map written to data-dir

##### Putting it all together
– Top layer: External IPv6 network ↔ Kernel IPv6 Stack
– Middle layer: TUN Interface ↔ TAYGA Daemon ↔ Mapping Store
– Bottom layer: Kernel IPv4 Stack ↔ External IPv4 network
– Side notes: iptables/ip6tables for firewalling, Autoconf/Make for build/install

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Networks
    subgraph "External Networks"
        v6["IPv6 Network"]:::ipv6
        v4["IPv4 Network"]:::ipv4
    end

    %% Kernel Stack & TUN
    subgraph "Kernel & TUN Interface"
        k6["Kernel IPv6 Stack"]:::kernel
        tun["TUN Interface\n(/dev/net/tun)"]:::kernel
        k4["Kernel IPv4 Stack"]:::kernel
    end

    %% TAYGA Daemon Process
    tayga["TAYGA Daemon\n(stateless NAT64)"]:::process

    %% Mapping Store & Config
    dynamicMap["dynamic.map"]:::storage
    taygaConf["tayga.conf"]:::config

    %% Daemon Modules
    subgraph "TAYGA Daemon Modules"
        mainC["tayga.c"]:::code
        mainH["tayga.h"]:::code
        nat64["nat64.c"]:::code
        addrmap["addrmap.c"]:::code
        dynamicMod["dynamic.c"]:::code
        conffile["conffile.c"]:::code
        configH["config.h.in"]:::code
    end

    %% Build & Install
    subgraph "Build & Install"
        confAC["configure.ac"]:::code
        mA["Makefile.am"]:::code
        mI["Makefile.in"]:::code
        inst["install-sh\nmissing\ndepcomp"]:::script
        lic["COPYING\nREADME\naclocal.m4\nconfigure\ndepcomp"]:::meta
    end

    %% Sample Config & Man Pages
    subgraph "Configuration Templates & Docs"
        taygaConfEx["tayga.conf.example"]:::config
        manConf["tayga.conf.5"]:::config
        manDaemon["tayga.8"]:::config
    end

    %% Packet Flows
    v6 -->|"IPv6"| k6 -->|"IPv6"| tun -->|"IPv6"| tayga
    tayga -->|"IPv4"| tun -->|"IPv4"| k4 -->|"IPv4"| v4

    %% Control & Config Flows
    taygaConf -.->|reads| tayga
    dynamicMap -.->|writes| tayga

    %% Module Associations
    mainC --> tayga
    mainH --> tayga
    nat64 --> tayga
    addrmap --> tayga
    dynamicMod --> tayga
    conffile --> tayga
    configH --> tayga

    %% Build & Install Integration
    confAC --> tayga
    mA --> tayga
    mI --> tayga
    inst --> tayga
    lic --> tayga

    %% Sample Config Integration
    taygaConfEx --> tayga
    manConf --> tayga
    manDaemon --> tayga

    %% Click Events
    click mainC "https://github.com/openthread/tayga/blob/master/tayga.c"
    click mainH "https://github.com/openthread/tayga/blob/master/tayga.h"
    click nat64 "https://github.com/openthread/tayga/blob/master/nat64.c"
    click addrmap "https://github.com/openthread/tayga/blob/master/addrmap.c"
    click dynamicMod "https://github.com/openthread/tayga/blob/master/dynamic.c"
    click conffile "https://github.com/openthread/tayga/blob/master/conffile.c"
    click configH "https://github.com/openthread/tayga/blob/master/config.h.in"
    click confAC "https://github.com/openthread/tayga/blob/master/configure.ac"
    click mA "https://github.com/openthread/tayga/blob/master/Makefile.am"
    click mI "https://github.com/openthread/tayga/blob/master/Makefile.in"
    click taygaConfEx "https://github.com/openthread/tayga/blob/master/tayga.conf.example"
    click manConf "https://github.com/openthread/tayga/blob/master/tayga.conf.5"
    click manDaemon "https://github.com/openthread/tayga/blob/master/tayga.8"
    click inst "https://github.com/openthread/tayga/tree/master/install-sh"
    click lic "https://github.com/openthread/tayga/tree/master/COPYING"

    %% Styles
    classDef ipv6 fill:#C0E0FF,stroke:#000;
    classDef ipv4 fill:#C0FFC0,stroke:#000;
    classDef kernel fill:#F0F0F0,stroke:#000;
    classDef process fill:#FFF0F0,stroke:#000;
    classDef storage fill:#FFD580,stroke:#000;
    classDef config fill:#FFD580,stroke:#000;
    classDef code fill:#E0E0E0,stroke:#000;
    classDef script fill:#E8D7F0,stroke:#000;
    classDef meta fill:#E5E5E5,stroke:#000;
```
