bpf

README

BPF

Intro

This directory is all about BPF programs and management. It includes:

• TCP Accept Event Probe: captures TCP accept event information. With time, pid, address and port information.
• TCP Connect Event Probe: captures TCP connect event information. With time, pid, address and port information.
• TCP Close Event Probe: captures TCP close event information. With basic info and traffic statistics.
• Network Subsystem Probe: traces key network event in host, for most scenarios in this project, network stack events around the pod.
• TCP Socket Redirect: attaches sockops and SK_MSG programs to cgroup v2, and redirect local TCP connection (both sidecar and pods on the same host) to bypass TCP/IP protocol stack.
• BPF Header Files: provides minimal BPF dependency header files, in order to compile

For most probes, they can filter by process id, and notify you by Go channel.

For functional BPF programs, they can run in the background, until a termination signal is received.

BFP Develop Guide

Performance event BPF programs

For scalability reasons, development based on BCC and gobpf library.

1. Define event struct for both C and Go. For network tracing, maybe you have to provide both IPv4 and IPv6 versions.
2. Write your tracing code by C, which must match the argument list.
3. Insert filter policy code dynamically. Filtering by pid is the most frequently used policy.
4. Attach your code to instrumentation point.
5. Initialize your event map, and got its Go channel.
6. Start a goroutine and wait for event to happen.
7. Process the event struct to user-friendly format and submit to the upper caller.

Functional BPF programs

For functional and performance reasons, Go library github.com/cilium/ebpf is used for implementation.

1. Write BPF C programs, and define relevant maps.
2. Use bpf2go tool to generate BPF byte code and Go file from C code. Usually use a go generate command at the top of the Go file.
3. Load all programs and maps via interface in generated Go files.
4. Pass information of the upper-level to the maps. (optional)
5. Attach the BPF programs to specified position.
6. Define unload and unpin logic for detaching BPF programs.

Hints

To develop BPF program in Go, here are some best practices hints. Maybe they are useful for you.

1. Keep your event struct aligned in 8 byte. Compiler always do some unknowable things when we write not aligned code. For some time, the compiler of C and the compiler of Go organize your struct differently. And, when you read binary data from C to Go, they will come out and make trouble. So, keep your data structure aligned to avoid it.
2. Use /*FILTER*/ as placeholder for inserting filter code. That can make sure your code can work even if you don't provide filter code.
3. In iovisor/bcc@ffff0ed, bcc_func_load's signature was changed. However, gobpf still lacks of maintenance on this. So, we should change the library as this PR. As a workaround, we extracted this as a new library, and just need use replace directive replace github.com/iovisor/gobpf => github.com/eswzy/gobpf v0.2.1-0.20220720201619-9eb793319a76 in go.mod file (after go get github.com/eswzy/gobpf@0.24.0).
4. For functional BPF programs, encapsulate load, attach and unload functions respectively. The specific behaviors should be implemented in user mode.

See Also

BPF and XDP Reference Guide

eBPF Mistake Avoidance Guide (blog in Chinese)

Documentation

Index

• Constants
• func AttachKprobe(m *bcc.Module, name string, fnName string)
• func AttachKretprobe(m *bcc.Module, name string, fnName string)
• func AttachTracepoint(m *bcc.Module, name string, fnName string)
• func GetAllHooks(pattern string) ([]string, error)
• func GetFamilyFilter(family string) string
• func GetFilterByParentProcessPidNamespace(rootPid int, pidList []int, reverse bool) (string, error)
• func GetHookFullName(pattern string) (string, error)
• func GetIpv4AndIpv6ReverseFilter() string
• func GetIpv4Filter() string
• func GetIpv6Filter() string
• func GetProtocolFromInt(p int) string
• func GetTcpFlags(f int, reversed bool) string
• func GetValueFromMap(m bcc.Table, key uint32)
• func TracepointExists(category string, event string) bool
• type FamilyFilterGenerator
  • func (fg FamilyFilterGenerator) Generate() string
• type IntFilterGenerator
  • func (fg IntFilterGenerator) Generate() string

Constants

const TraceFs = "/sys/kernel/debug/tracing"

Functions

func AttachKprobe

func AttachKprobe(m *bcc.Module, name string, fnName string)

func AttachKretprobe

func AttachKretprobe(m *bcc.Module, name string, fnName string)

func AttachTracepoint

func AttachTracepoint(m *bcc.Module, name string, fnName string)

func GetAllHooks

func GetAllHooks(pattern string) ([]string, error)

GetAllHooks gets all hooks

func GetFamilyFilter

func GetFamilyFilter(family string) string

func GetFilterByParentProcessPidNamespace

func GetFilterByParentProcessPidNamespace(rootPid int, pidList []int, reverse bool) (string, error)

func GetHookFullName

func GetHookFullName(pattern string) (string, error)

GetHookFullName gets the full name for hook point, mostly for C++ symbols.

func GetIpv4AndIpv6ReverseFilter

func GetIpv4AndIpv6ReverseFilter() string

func GetIpv4Filter

func GetIpv4Filter() string

func GetIpv6Filter

func GetIpv6Filter() string

func GetProtocolFromInt

func GetProtocolFromInt(p int) string

func GetTcpFlags

func GetTcpFlags(f int, reversed bool) string

GetTcpFlags gets TCP flags from combined field

func GetValueFromMap

func GetValueFromMap(m bcc.Table, key uint32)

GetValueFromMap gets value from table for usage record only

func TracepointExists

func TracepointExists(category string, event string) bool

Types

type FamilyFilterGenerator

type FamilyFilterGenerator struct {
	List []string
}

func (FamilyFilterGenerator) Generate

func (fg FamilyFilterGenerator) Generate() string

type IntFilterGenerator

type IntFilterGenerator struct {
	Name    string
	List    []int
	Action  string
	Reverse bool // skip event if `Reverse` is true
}

func (IntFilterGenerator) Generate

func (fg IntFilterGenerator) Generate() string

Generate generate filter statement for BPF program in C code