How mirantis/dhcp-relay works
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