# mirantis/dhcp-relay architecture

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

- Interactive diagram: https://gitdiagram.com/mirantis/dhcp-relay
- Repository: https://github.com/mirantis/dhcp-relay

## Overview

##### Project type and purpose
- This is a standalone, opinionated DHCPv4 relay agent written in Go.
- It sits in user-space on a Linux host (often in Kubernetes with hostNetwork) and forwards DHCPv4 packets between clients and a DHCPv4 server.
- Key capabilities: AF_PACKET raw sockets, in-kernel BPF filtering, minimal CLI, on-demand pprof endpoints.

##### File structure
Top-level
- main.go – application entry point and CLI setup
- config.go, validate.go, version/version.go – global configuration, validation, version info
- debug.go – exposes pprof HTTP endpoints
- addrs.go, random.go – utilities for IP addressing and transaction ID generation
- dhcpv4.go, dhcpv4-request.go, dhcpv4-reply.go – core relay logic
- bytecode/ – BPF bytecode generator (bytecode/bpf.go, const.go)
- gpckt/ – packet parsing library (layers: ethernet, IPv4, UDP, DHCP)
- sockets/ – raw socket and packet listener abstraction
- specs/ – protocol constants and header formats
- logger/ – structured logging abstraction
- Dockerfile, Makefiles, GitHub workflows – build and CI/CD

##### README for additional insights
- Describes runtime requirements (Linux kernel BPF, CAP_NET_RAW)
- Lists features (kernel-space filtering, dynamic DNS, no restarts) and non-features (DHCPv6, RFC3396, hot reload)
- Points to external RFCs and docs

##### Components
a. Main Components
1. Network Interfaces (Downstream network / Clients)
2. Linux Kernel + BPF Engine (AF_PACKET hook)
3. Relay Agent User-Space Process
– Socket Layer (sockets/raw.go, sockets/packet.go, misc.go)
– BPF Loader (bytecode/bpf.go)
– Packet Parser (gpckt/*)
– Relay Logic (dhcpv4*.go)
– Utilities (config.go, validate.go, random.go, addrs.go)
– Debug & Metrics (debug.go → pprof)
– Logger (logger/logger.go)
4. Upstream DHCPv4 Server (could be IP or k8s Service DNS)
b. Relationships & Data Flows
1. Raw Ethernet frames from network → AF_PACKET socket (kernel)
2. BPF filter in kernel filters DHCPv4 packets → user socket
3. User-space socket receives packet → gpckt parses Ethernet/IPv4/UDP/DHCP headers
4. Relay logic inspects, optionally validates → forwards to DHCPv4 server socket
5. DHCPv4 server reply packets follow the reverse path back to clients
6. CLI config flows into startup (defines server address or DNS)
7. debug.go exposes pprof over HTTP on specified port for on-demand profiling
c. Architectural Patterns & Design Principles
- Layered networking stack separation (kernel vs user-space)
- Modular Go packages (single responsibility for bytecode, parsing, sockets)
- Minimal external dependencies (standard library + small gpckt lib)
- CI/CD workflows enforce linting, testing, vendor checks, Docker builds
d. Key Technologies, Frameworks, Libraries
- Golang (modules, standard net package, pprof, Go toolchain)
- Linux AF_PACKET sockets + BPF filters
- gpckt for packet decoding/encoding
- Docker & Kubernetes hostNetwork

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Clients\n(DHCP Discover)"]:::external

    %% Kernel Layer
    subgraph "Linux Kernel\n(AF_PACKET + BPF Filter)" 
        Kernel["AF_PACKET Hook\n+ BPF Engine"]:::kernel
    end

    %% User-space Process
    subgraph "User-space Process"
        subgraph "CLI & Startup"
            Main["main.go\n(CLI)"]:::user
            Version["version/version.go"]:::user
            Main -->|version info| Version
        end

        subgraph "Utilities"
            Config["config.go"]:::user
            Validate["validate.go"]:::user
            Addrs["addrs.go"]:::user
            Random["random.go"]:::user
            Main -->|initialize| Config
            Main -->|initialize| Validate
            Main -->|initialize| Addrs
            Main -->|initialize| Random
        end

        subgraph "Observability"
            Debug["debug.go\n(pprof HTTP)"]:::observ
            Logger["logger/logger.go"]:::user
            Main -->|start pprof HTTP| Debug
            Main -->|initialize logger| Logger
        end

        subgraph "Packet Handling"
            subgraph "BPF Loader"
                BPFLoader1["bytecode/bpf.go"]:::user
                BPFConst["bytecode/const.go"]:::user
                Main -->|load BPF| BPFLoader1
                BPFLoader1 -->|install filter| Kernel
            end

            subgraph "Socket Layer"
                Raw["sockets/raw.go"]:::user
                PacketListener["sockets/packet.go"]:::user
                SocketsMisc["sockets/misc.go"]:::user
            end

            subgraph "Packet Parser"
                GpcktLayer["gpckt/layer.go"]:::parser
                GpcktDHCP["gpckt/dhcp/*"]:::parser
            end

            subgraph "Protocol Specs"
                EtherSpec["specs/ethernet.go"]:::user
                IPv4Spec["specs/ipv4.go"]:::user
                UDPSpec["specs/udp.go"]:::user
                DHCPv4Spec["specs/dhcpv4.go"]:::user
            end

            subgraph "Relay Logic"
                RelayMain["dhcpv4.go"]:::user
                RelayReq["dhcpv4-request.go"]:::user
                RelayRep["dhcpv4-reply.go"]:::user
            end
        end
    end

    %% Upstream DHCPv4 Server
    Server["Upstream DHCPv4 Server\n(UDP 67)"]:::external

    %% Packet Flow
    Client -->|Ethernet Frame| Kernel
    Kernel -->|BPF Filter| Raw
    Raw -->|packet| PacketListener
    PacketListener -->|raw data| GpcktLayer
    GpcktLayer -->|parse DHCP| GpcktDHCP
    GpcktDHCP -->|parsed DHCP| RelayMain
    RelayMain -->|DHCP Request| Server
    Server -->|DHCP Reply| RelayMain
    RelayMain -->|forward packet| PacketListener
    PacketListener -->|Ethernet Frame| Kernel
    Kernel -->|Ethernet Frame| Client

    %% Click Events
    click Main "https://github.com/mirantis/dhcp-relay/blob/main/main.go"
    click Version "https://github.com/mirantis/dhcp-relay/blob/main/version/version.go"
    click Config "https://github.com/mirantis/dhcp-relay/blob/main/config.go"
    click Validate "https://github.com/mirantis/dhcp-relay/blob/main/validate.go"
    click Addrs "https://github.com/mirantis/dhcp-relay/blob/main/addrs.go"
    click Random "https://github.com/mirantis/dhcp-relay/blob/main/random.go"
    click Debug "https://github.com/mirantis/dhcp-relay/blob/main/debug.go"
    click Logger "https://github.com/mirantis/dhcp-relay/blob/main/logger/logger.go"
    click BPFLoader1 "https://github.com/mirantis/dhcp-relay/blob/main/bytecode/bpf.go"
    click BPFConst "https://github.com/mirantis/dhcp-relay/blob/main/bytecode/const.go"
    click Raw "https://github.com/mirantis/dhcp-relay/blob/main/sockets/raw.go"
    click PacketListener "https://github.com/mirantis/dhcp-relay/blob/main/sockets/packet.go"
    click SocketsMisc "https://github.com/mirantis/dhcp-relay/blob/main/sockets/misc.go"
    click GpcktLayer "https://github.com/mirantis/dhcp-relay/blob/main/gpckt/layer.go"
    click GpcktDHCP "https://github.com/mirantis/dhcp-relay/tree/main/gpckt/dhcp"
    click EtherSpec "https://github.com/mirantis/dhcp-relay/blob/main/specs/ethernet.go"
    click IPv4Spec "https://github.com/mirantis/dhcp-relay/blob/main/specs/ipv4.go"
    click UDPSpec "https://github.com/mirantis/dhcp-relay/blob/main/specs/udp.go"
    click DHCPv4Spec "https://github.com/mirantis/dhcp-relay/blob/main/specs/dhcpv4.go"
    click RelayMain "https://github.com/mirantis/dhcp-relay/blob/main/dhcpv4.go"
    click RelayReq "https://github.com/mirantis/dhcp-relay/blob/main/dhcpv4-request.go"
    click RelayRep "https://github.com/mirantis/dhcp-relay/blob/main/dhcpv4-reply.go"

    %% Styles
    classDef external fill:#c2f0c2,stroke:#2d572c;
    classDef kernel fill:#e0e0e0,stroke:#888;
    classDef user fill:#c2e0ff,stroke:#036;
    classDef parser fill:#ffd580,stroke:#996515;
    classDef observ fill:#ffe6e6,stroke:#cc0000;
```
