bpfviewer - eBPF Disassembler & Visualizer

A developer tool for disassembling, analyzing, debugging, and visualizing BPF object files.

Background & Motivation

eBPF development can be challenging, especially when dealing with BPF program load errors. While the kernel provides verbose error messages through bpftool prog dump xlated and the verifier log, mapping these errors back to the original source code is often difficult and time-consuming.

Existing tools like llvm-objdump provide basic disassembly, but they lack:

Visual representation of program-to-map relationships
Easy-to-read instruction formatting
Quick navigation between programs and their associated data structures
Web-based interactive viewing

bpfviewer was created to fill this gap. It provides a comprehensive view of your compiled BPF object files, making it easier to:

Debug BPF loading failures
Understand the compiled output
Visualize how programs interact with maps
Bridge the gap between kernel verifier output and your source code

We hope this tool will make eBPF development more productive and less frustrating.

Features

Disassembly

Full BPF instruction disassembly from ELF object files
Human-readable instruction formatting with register names
Source-to-instruction mapping — displays BPF instructions alongside corresponding source code for easier debugging and understanding of compiler optimizations
Program metadata including section, type, and instruction offset
Support for all standard BPF instruction types
Note: BPF programs must be compiled with the -g option to preserve debug information

Visualization

Mermaid flow graphs showing program-to-map relationships
Automatic detection of map operations (Lookup, Update, Delete)
Interactive HTML output with syntax highlighting
Side-by-side view of disassembly code and relationship graphs

Dual Mode Operation

CLI mode: Generate a standalone HTML file from a BPF object
Daemon mode: HTTP server with web UI for uploading and viewing multiple files

Installation

go build -o bpfviewer main.go ins.go

Usage

CLI Mode

Generate an HTML file from a BPF object file:

./bpfviewer -f <bpf-file>

Options:

-f, --file: BPF object file to parse (required)
-t, --temp: HTML template file (default: bpf_template.html)
--host: Home page URL for the back button
--version: Show version and exit

Example:

./bpfviewer -f tracer.o
# Output: tracer.html

Daemon Mode

Run as an HTTP server with web UI:

./bpfviewer --daemon [--listen :8086]

Options:

--daemon: Run in daemon mode (HTTP server)
--listen: Listen address (default: :8086)

The server provides:

File upload via drag-and-drop web UI
Automatic HTML generation on demand
File management (list, view, delete)
Pre-generated HTML file serving

Open http://localhost:8086 in your browser to access the web interface.

Output Example

The generated HTML includes:

Source Section: Disassembled BPF instructions
Graph Section: Visual relationship diagram

Project Structure

bpfviewer/
├── main.go           # Main program logic, HTTP handlers
├── ins.go            # BPF instruction disassembly & formatting
├── bpf_template.html # Template for generated HTML visualization
├── home.html         # Home page for daemon mode
├── bpf/              # Directory for uploaded BPF object files
└── html/             # Directory for generated HTML files

Dependencies

cilium/ebpf - eBPF library for Go
logrus - Structured logger
pflag - POSIX-compliant command-line flags

Comparison with Other Tools

| Tool | Disassembly | Visualization | Web UI | Prog-Map Relationships | |------|-------------|---------------|--------|-------------------| | bpfviewer | ✅ | ✅ | ✅ | ✅ | | llvm-objdump | ✅ | ❌ | ❌ | ❌ | | bpftool | ✅ | ❌ | ❌ | Limited |

License

Licensed under the Apache License, Version 2.0 or the Mulan Permissive Software License, Version 2 (Mulan PSL v2). You may choose either license to govern your use of this software.

Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0
Mulan PSL v2: https://license.coscl.org.cn/MulanPSL2

Unless required by applicable law or agreed to in writing, software distributed under either license is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.

Bpfviewer

Install / Use

README