# murilochianfa/srv6-pot-tlv architecture

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

- Interactive diagram: https://gitdiagram.com/murilochianfa/srv6-pot-tlv
- Repository: https://github.com/murilochianfa/srv6-pot-tlv

## Overview

##### Project type and purpose
- This is a specialized network-function project that implements an eBPF-based Proof-of-Transit TLV mechanism for SRv6.
- It comprises three “planes”:
a. Data Plane: eBPF bytecode attached at XDP and TC hooks in the Linux kernel.
b. Control Plane: A Go-based CLI (`cmd/main.go`) that loads/unloads BPF programs, pins and updates key maps, and interacts with the kernel’s BPF subsystem.
c. Deployment/Orchestration Plane: An Ansible/QEMU-based topology under `topology/` to spin up SRv6 routers and hosts, plus Python scripts under `tests/` to evaluate performance.

##### File structure
- `bpf/` – contains eBPF C headers and source (`seg6-pot-tlv.bpf.c` at root) implementing:
- Crypto primitives (SipHash, Poly1305, BLAKE3)
- SRv6 header parsing (`hdr.h`, `srh.h`, `tlv.h`)
- PoT TLV operations (`pot/add.h`, `pot/update.h`, `pot/remove.h`)
- `cmd/` – Go CLI using libbpf to: load programs into XDP/TC, pin maps, and manage SID→key entries.
- `topology/` – Ansible inventories and playbooks, shell scripts, and cloud-init metadata to build a multi-node SRv6 domain in QEMU VMs.
- `tests/` – Python scripts and data for gathering RTT, plotting results, and debug TRACING.

##### README for additional insights
- The README describes the SRv6 packet format, the TLV layout, usage of the CLI tool, debugging commands (`bpftool`, `tcpdump`), and end-to-end demonstration with QEMU topology.
- It clarifies the three crypto algorithms and the phases: compile BPF bytecode, load via CLI, update key map, generate traffic, and verify PoT in the TLV.

a. User-Space CLI (Go binary “seg6-pot-tlv”)
b. Kernel eBPF Subsystem:
- XDP Program (pre-routing)
- TC BPF Program (ingress qdisc)
- BPF Maps (SID→Key store)
c. Linux Kernel Networking Stack – SRv6 packet handling
d. Virtual Network Topology (Hosts H1/H2 and Routers R1…R4)
e. Test Harness & Orchestration:
- Ansible + QEMU for deployment
- Python scripts for performance measurement
f. External Tools & Interfaces:
- bpftool, tcpdump/tshark for debugging
- iproute2 for SRv6 route configuration

Relationships & Data Flows:
- The CLI invokes netlink/libbpf to load XDP+TC programs into the kernel on a target interface.
- The CLI populates BPF maps (pinned under `/sys/fs/bpf/…`) with SID→32B keys.
- Incoming SRv6 packets hit the XDP hook → TLV is parsed/updated (crypto is invoked).
- Packets pass to the kernel’s SRv6 processing → forwarded to next hop → possibly hit TC hook on egress for final TLV update or verification.
- Debug tools tap kernel logs and packet streams.
- Ansible orchestrates VM creation, network links, and auto-loads the CLI on each router.
- Tests generate traffic from H1→H2 and collect end-to-end RTT or TLV contents.

##### Architectural Patterns & Design Principles
- Clear separation of Control Plane (Go CLI) vs Data Plane (eBPF code).
- Use of BPF maps as shared, pinned key-value stores.
- Modular BPF code: distinct headers for parsing SRH, TLV, crypto, and PoT operations.
- CO-RE style eBPF for portability across kernel versions (libbpf).
- Infrastructure-as-code (Ansible + QEMU) for reproducible deployments.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Orchestration Plane" 
        direction TB
        ANS["Ansible Playbook"]:::orchestration
        TOPO["QEMU Topology"]:::orchestration
        ANS -->|deploy VMs & config| TOPO
    end

    subgraph "Control Plane" 
        direction TB
        CLI["Go CLI\n(seg6-pot-tlv)"]:::control
        BPFTOOL["bpftool/tcpdump"]:::control
        IPROUTE2["iproute2"]:::control
        CLI -->|libbpf/netlink| BPF_SUBSYS
        CLI -->|BPFFS map pin| MAPS
        BPFTOOL --- CLI
        IPROUTE2 --- CLI
    end

    subgraph "Data Plane" 
        direction TB
        subgraph "Linux Kernel (per VM)"
            direction TB
            IF_IN["Network Interface"]:::data
            XDP["XDP BPF Program"]:::data
            SRV6["SRv6 Stack"]:::data
            TC["TC BPF Program"]:::data
            IF_OUT["Network Interface"]:::data
            MAPS["BPF Maps\n(SID→Key)"]:::data
            IF_IN -->|packet flow| XDP
            XDP -->|parse/update TLV| SRV6
            SRV6 -->|forward| TC
            TC -->|final TLV ops| IF_OUT
            XDP -- "access" --> MAPS
            TC  -- "access" --> MAPS
        end
    end

    subgraph "Test & Evaluation"
        direction TB
        TESTS["Test Scripts"]:::test
        COLLECT["collect-round-trip-time.py"]:::test
        EVAL["evaluate-using-box-plot.py"]:::test
        TESTS -->|generate traffic| IF_IN
        IF_OUT -->|collect RTT| COLLECT
        COLLECT --> EVAL
    end

    %% Connections between planes
    TOPO -->|auto-load CLI| CLI
    TOPO -->|provision kernel hooks| XDP
    TOPO -->|provision kernel hooks| TC

    %% Click Events
    click CLI "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/cmd/main.go"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/topology/playbook.yml"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/inventory"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/topology/setup.sh"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/topology/topology.sh"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/topology/cleanup.sh"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/topology/kill-qemu.sh"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/h1/"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/h2/"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/r1/"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/r2/"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/r3/"
    click TOPO "https://github.com/murilochianfa/srv6-pot-tlv/tree/main/topology/r4/"
    click BPF_CODE "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/seg6-pot-tlv.bpf.c"
    click HDR "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/hdr.h"
    click SRH "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/srh.h"
    click TLV "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/tlv.h"
    click EXP "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/exp.h"
    click BLAKE3 "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/crypto/blake3.h"
    click POLY1305 "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/crypto/poly1305.h"
    click SIPHASH "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/crypto/siphash.h"
    click NONCE "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/crypto/nonce.h"
    click KEYS "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/crypto/keys.h"
    click ADD "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/pot/add.h"
    click UPDATE "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/pot/update.h"
    click REMOVE "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/bpf/pot/remove.h"
    click COLLECT "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/tests/evaluation/collect-round-trip-time.py"
    click EVAL "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/tests/evaluation/evaluate-using-box-plot.py"
    click TESTS "https://github.com/murilochianfa/srv6-pot-tlv/blob/main/tests/debug/README.md"

    %% Node definitions for click mappings
    BPF_CODE["seg6-pot-tlv.bpf.c"]:::data
    HDR["hdr.h"]:::data
    SRH["srh.h"]:::data
    TLV["tlv.h"]:::data
    EXP["exp.h"]:::data
    BLAKE3["blake3.h"]:::data
    POLY1305["poly1305.h"]:::data
    SIPHASH["siphash.h"]:::data
    NONCE["nonce.h"]:::data
    KEYS["keys.h"]:::data
    ADD["add.h"]:::data
    UPDATE["update.h"]:::data
    REMOVE["remove.h"]:::data

    %% Styles
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
    classDef control fill:#9f6,stroke:#333,stroke-width:1px
    classDef data fill:#6cf,stroke:#333,stroke-width:1px
    classDef test fill:#f96,stroke:#333,stroke-width:1px

    %% BPF subsystem placeholder
    BPF_SUBSYS((Kernel BPF Subsystem)):::data
    MAPS((BPF Maps)):::data

    %% Arrange layering
    class ANS,TOPO orchestration
    class CLI,BPFTOOL,IPROUTE2 control
    class IF_IN,XDP,SRV6,TC,IF_OUT,BPF_SUBSYS,MAPS data
    class TESTS,COLLECT,EVAL test
```
