libbpfgo

libbpfgo abstracts C technicalities into idiomatic Go patterns: it translates low-level return codes into Go error types, organizes functionality around Go structs, and uses Go channels for event consumption.

A typical workflow for using the library is:

1. Compile: Compile your BPF program into an object file.
2. Initialize Module: Create a Module struct representing the unit of BPF functionality around your compiled object file.
3. Load Programs: Use the BPFProg struct to load BPF programs from the object file.
4. Attach: Attach BPFProg to system facilities (e.g., "raw tracepoints" or "kprobes") using its associated functions.
5. Manage Maps: Use the BPFMap struct and its methods to instantiate and manipulate BPF Maps.
6. Handle Events: Use the RingBuffer struct and its associated objects to communicate events from your BPF program to userspace via channels.

// initializing
import bpf "github.com/aquasecurity/libbpfgo"
...
bpfModule := bpf.NewModuleFromFile(bpfObjectPath)
bpfModule.BPFLoadObject()

// maps
mymap, _ := bpfModule.GetMap("mymap")
mymap.Update(key, value)

// ring buffer
rb, _ := bpfModule.InitRingBuffer("events", eventsChannel, buffSize)
rb.Poll(300)
e := <-eventsChannel

The project provides several GNU Makefile rules for different linking strategies.

Dynamic Linking (Uses OS libbpf)

Requires a recent enough libbpf package and headers installed on your OS.

• make libbpfgo-dynamic: Builds dynamic libbpfgo.
• make libbpfgo-dynamic-test: Runs go test with dynamic libbpfgo.
• make selftest-dynamic: Builds tests with dynamic libbpfgo.
• make selftest-dynamic-run: Runs tests using dynamic libbpfgo.

Static Linking (Uses libbpf submodule)

Note: You must run git submodule init to sync the libbpf submodule before building.

• make libbpfgo-static: Builds static libbpfgo.
• make libbpfgo-static-test: Runs go test with static libbpfgo.
• make selftest-static: Builds tests with static libbpfgo.
• make selftest-static-run: Runs all static selftests.

General Rules

• make all: Builds libbpfgo (dynamic).
• make clean: Cleans the entire tree.

# Example: Build statically linked libbpfgo
$ make libbpfgo-static

# Example: Build and run all static selftests
$ make selftest-static-run

The RingBuffer type is used to poll and consume data from an eBPF ring buffer. It manages a background goroutine that calls the underlying C ring_buffer__poll function.

To use it:

1. Initialize the RingBuffer (typically via a constructor not shown in this file, but linked to a BPFMap).
2. Call Poll(timeout) to start the background polling process. The timeout parameter specifies how long to wait in milliseconds.
3. Call Stop() to signal the polling goroutine to exit and to drain event channels to prevent deadlocks.
4. Call Close() to stop the buffer, free the underlying C memory (ring_buffer__free), and remove associated event channels.

// Example lifecycle of a RingBuffer
rb := &libbpfgo.RingBuffer{...}

// Start polling with a 300ms timeout
rb.Poll(300)

// ... perform work ...

// Stop the polling goroutine
rb.Stop()

// Clean up resources and C memory
rb.Close()

The PerfBuffer type is used to consume events from an eBPF perf buffer. It provides a mechanism to poll for data and receive events via a Go channel.

To use a PerfBuffer:

1. Initialize the buffer (typically via a constructor not shown in this file, but linked to a BPFMap).
2. Call Poll(timeout) to start an asynchronous goroutine that gathers data from the buffer.
3. The timeout parameter specifies how long to wait in milliseconds for data during each poll cycle.
4. Listen to the eventsChan for incoming []byte data.
5. Call Stop() to signal the polling goroutine to exit and drain remaining channels to prevent deadlocks.
6. Call Close() to stop the buffer and free the underlying C resources.

// Example usage pattern
// Note: Initialization of PerfBuffer is assumed to happen via other libbpfgo APIs

// Start polling with a 300ms timeout
pb.Poll(300)

// Consume events in a loop
go func() {
    for event := range pb.eventsChan {
        fmt.Printf("Received event: %x\n", event)
    }
}()

// ... later ...

pb.Stop()
pb.Close()