wbpf

package module
v0.0.0-...-0fcddf3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 30, 2024 License: Apache-2.0 Imports: 27 Imported by: 0

README

wbpf - Wrapped BPF

CI

This library is a wrapper layer for Cilium eBPF. It takes inspiration from BCC and Cilium.

Documentation

Index

Constants

View Source 
const DEFAULT_PERF_BUF_SIZE = 1024 * 1024
View Source 
const MAX_STACK_DEPTH = 127

Variables

View Source 
var (
	ErrTableNotFound      = fmt.Errorf("table not found")
	ErrIncorrectTableType = fmt.Errorf("incorrect table type")
	ErrTableIsNil         = fmt.Errorf("table is nil")
)
View Source 
var ErrNoSymbolsFound = fmt.Errorf("no symbols found")
View Source 
var ErrProgNotFound = fmt.Errorf("prog not found")

Functions

func FixSyscallName 

func FixSyscallName(name string) string

func GetSyscallName 

func GetSyscallName(name string) string

func GetSyscallPrefix 

func GetSyscallPrefix() string

Types

type ArrayTable 

type ArrayTable[T any] struct{ *Table }

func NewArrayTable 

func NewArrayTable[T any](tbl *Table) (*ArrayTable[T], error)

func (*ArrayTable[T]) Get 

func (t *ArrayTable[T]) Get(idx uint32, out *T) error

func (*ArrayTable[T]) Set 

func (t *ArrayTable[T]) Set(idx uint32, val T, flag UpdateFlag) error

type Module 

type Module struct {
	// contains filtered or unexported fields
}

func NewModule 

func NewModule(opts ...ModuleOption) (*Module, func() error, error)

NewModule creates a new eBPF module from the given file or content. Only one of file or content must be specified. Returns: - The module - A function that must be called after attaching the Collection's entrypoint programs to their respective hooks - An error if the module could not be created

func (*Module) AttachFEntry 

func (m *Module) AttachFEntry(prog string) (link.Link, error)

func (*Module) AttachFExit 

func (m *Module) AttachFExit(prog string) (link.Link, error)

func (*Module) AttachKprobe 

func (m *Module) AttachKprobe(sysname, prog string) (link.Link, error)

Kprobe attaches the given eBPF program to a perf event that fires when the given kernel symbol starts executing. See /proc/kallsyms for available symbols. For example, printk(): 

err := mod.AttachKprobe("printk", prog)

This function will assume that the syscall is correct. Therefore, the input syscall must be fixed before pass through this.

func (*Module) AttachKretprobe 

func (m *Module) AttachKretprobe(sysname, prog string) (link.Link, error)

AttachKretprobe attaches the given eBPF program to a perf event that fires right before the given kernel symbol exits, with the function stack left intact. See /proc/kallsyms for available symbols. For example, printk(): 

kp, err := Kretprobe("printk", prog, nil)

This function will assume that the syscall is correct. Therefore, the input syscall must be fixed before pass through this.

func (*Module) AttachLSM 

func (m *Module) AttachLSM(prog string) (link.Link, error)

AttachLSM links a Linux security module (LSM) BPF Program to a BPF hook defined in kernel modules.

func (*Module) AttachModifyReturn 

func (m *Module) AttachModifyReturn(prog string) (link.Link, error)

func (*Module) AttachPerfEvent 

func (m *Module) AttachPerfEvent(prog string, opts PerfEventOptions) error

AttachPerfEvent attaches the given eBPF program to a perf event that fires when the given event occurs. See /sys/bus/event_source/devices/ for available events.

func (*Module) AttachRawTracepoint 

func (m *Module) AttachRawTracepoint(name, prog string) (link.Link, error)

AttachRawTracepoint attaches a raw tracepoint to the input prog. The input name is in the format 'name', there is no group.

func (*Module) AttachTracepoint 

func (m *Module) AttachTracepoint(name, prog string) (link.Link, error)

AttachTracepoint attaches a tracepoint to the input prog. The input name must be in the format 'group:name'

func (*Module) AttachTracing 

func (m *Module) AttachTracing(prog string, typ ebpf.AttachType) (link.Link, error)

AttachTracing links a tracing (fentry/fexit/fmod_ret) BPF program or a BTF-powered raw tracepoint (tp_btf) BPF Program to a BPF hook defined in kernel modules.

func (*Module) AttachUprobe 

func (m *Module) AttachUprobe(module, prog string, opts *UprobeOptions) error

AttachUprobe attaches the given eBPF program to a perf event that fires when the given symbol starts executing in the given Executable. For example, /bin/bash::main(): 

mod.AttachUprobe("/bin/bash", prog, &UprobeOptions{SymbolName: "main"})

When using symbols which belongs to shared libraries, an offset must be provided via options: 

mod.AttachUprobe("/bin/bash", prog, &UprobeOptions{SymbolName: "main", Offset: 0x123})

Note: Setting the Offset field in the options supersedes the symbol's offset.

You also able to attach multi-symbols by regex matching: 

mod.AttachUprobe("/bin/bash", prog, &UprobeOptions{SymbolPattern: "ma*"})

Note: Only SymbolPattern or SymbolName must be specified

Losing the reference to the resulting Link (up) will close the Uprobe and prevent further execution of prog. The Link must be Closed during program shutdown to avoid leaking system resources.

Functions provided by shared libraries can currently not be traced and will result in an ErrNotSupported.

func (*Module) AttachUretprobe 

func (m *Module) AttachUretprobe(module, prog string, opts *UprobeOptions) error

AttachUretprobe attaches the given eBPF program to a perf event that fires right before the given symbol exits. For example, /bin/bash::main(): 

mod.AttachURetprobe("/bin/bash", prog, &UprobeOptions{SymbolName: "main"})

When using symbols which belongs to shared libraries, an offset must be provided via options: 

mod.AttachUprobe("/bin/bash", prog, &UprobeOptions{SymbolName: "main", Offset: 0x123})

Note: Setting the Offset field in the options supersedes the symbol's offset.

You also able to attach multi-symbols by regex matching: 

mod.AttachUprobe("/bin/bash", prog, &UprobeOptions{SymbolPattern: "ma*"})

Note: Only SymbolPattern or SymbolName must be specified

Losing the reference to the resulting Link (up) will close the Uprobe and prevent further execution of prog. The Link must be Closed during program shutdown to avoid leaking system resources.

Functions provided by shared libraries can currently not be traced and will result in an ErrNotSupported.

func (*Module) AttachXDP 

func (m *Module) AttachXDP(ifname, prog string, flags uint64) (link.Link, error)

AttachXDP links an XDP BPF program to an XDP hook. The input ifname is the name of the network interface to which you want to attach the input program. The input flags must conform to the link.XDPAttachFlags enum.

func (*Module) Close 

func (m *Module) Close()

Close closes the module and all of its resources. This function is expected to be call when the module is no longer needed to avoid resource leak.

func (*Module) ClosePerfBuffer 

func (m *Module) ClosePerfBuffer(name string)

ClosePerfBuffer closes the perf buffer with the given name.

func (*Module) CloseRingBuffer 

func (m *Module) CloseRingBuffer(name string)

CloseRingBuffer closes the ring buffer with the given name.

func (*Module) DetachKprobe 

func (m *Module) DetachKprobe(sysname, prog string)

DetachKprobe detaches the kprobe with the given name. If the input prog is empty, all kprobes with the given name will be detached.

func (*Module) DetachPerfEvent 

func (m *Module) DetachPerfEvent(prog string)

func (*Module) DetachRawTracepoint 

func (m *Module) DetachRawTracepoint(name, prog string)

DetachRawTracepoint detaches the raw tracepoint with the given name and prog. The input name is in the format 'name', there is no group. If the input prog is empty, all raw tracepoints with the given name will be detached.

func (*Module) DetachTracepoint 

func (m *Module) DetachTracepoint(name, prog string)

DetachTracepoint detaches the tracepoint with the given name. The input name must be in the format 'group:name'. If the input prog is empty, all tracepoints with the given name will be detached.

func (*Module) DetachTracing 

func (m *Module) DetachTracing(prog string, typ ebpf.AttachType)

func (*Module) DetachXDP 

func (m *Module) DetachXDP(ifname, prog string)

DetachXDP detaches the XDP program from the given interface. If the input prog is empty, all XDP programs attached to the given interface will be detached.

func (*Module) GetOrCreateSymbolCache 

func (m *Module) GetOrCreateSymbolCache(pid int) syms.Resolver

func (*Module) GetPerfBuffer 

func (m *Module) GetPerfBuffer(name string) *PerfBuf

GetPerfBuffer returns the perf buffer with the given name. If the perf buffer is not found, nil will be returned.

func (*Module) GetProg 

func (m *Module) GetProg(name string) (*ebpf.Program, error)

func (*Module) GetRingBuffer 

func (m *Module) GetRingBuffer(name string) *RingBuf

GetRingBuffer returns the ring buffer with the given name.

func (*Module) GetTable 

func (m *Module) GetTable(name string) (*Table, error)

GetTable returns the table with the given name. Otherwise, an error will be returned.

func (*Module) Maps 

func (m *Module) Maps() map[string]*ebpf.Map

Maps return all the maps in the collection

func (*Module) OpenPerfBuffer 

func (m *Module) OpenPerfBuffer(name string, opts *PerfBufOptions) error

OpenPerfBuffer opens a perf buffer for the given table. The input opts is optional. If opts is nil, the default options will be used.

func (*Module) OpenRingBuffer 

func (m *Module) OpenRingBuffer(name string, opts *RingBufOptions) error

OpenRingBuffer opens a ring buffer for the given table. The input opts is optional.

func (*Module) PollPerfBuffer 

func (m *Module) PollPerfBuffer(name string, timeout time.Duration) int

PollPerfBuffer polls the perf buffer with the given name. If timeout is zero, the poll will return immediately. If timeout is negative, the poll will block until an event is available.

func (*Module) PollRingBuffer 

func (m *Module) PollRingBuffer(name string, timeout time.Duration) int

PollRingBuffer polls the ring buffer with the given name. If timeout is zero, the poll will return immediately. If timeout is negative, the poll will block until an event is available.

func (*Module) Programs 

func (m *Module) Programs() map[string]*ebpf.Program

Programs return all programs in the collection

func (*Module) ResolveKernelSymbol 

func (bpf *Module) ResolveKernelSymbol(addr uint64, opts ResolveSymbolOptions) string

ResolveKernelSymbol translate a kernel memory address into a kernel function name, which is returned. When the show module is set, the module name ("kernel") is also included. When the show offset is set, the instruction offset as a hexadecimal number is also included in the string

Example outout when both show module and show offset are set: 

"__x64_sys_epoll_pwait+0x00000077 [kernel]"

func (*Module) ResolveSymbol 

func (m *Module) ResolveSymbol(pid int, addr uint64, opts ResolveSymbolOptions) string

ResolveSymbol Translate a memory address into a function name for a pid, which is returned. When the show module option is set, the module name is also included. When the show offset is set, the instruction offset as a hexadecimal number is also included in the return string. A pid of lss than zero will access the kernel symbol cache.

Example output when both show module and show offset are set: 

"net/http.HandlerFunc.ServeHTTP+0x0000002f [.app]"

Example output when both show module and show offset are unset: 

"net/http.HandlerFunc.ServeHTTP"

type ModuleOption 

type ModuleOption func(*moduleOptions)

func WithCollectionOptions 

func WithCollectionOptions(opts ebpf.CollectionOptions) ModuleOption

func WithElfFile 

func WithElfFile(path string) ModuleOption

func WithElfFileContent 

func WithElfFileContent(content []byte) ModuleOption

func WithSymCacheSize 

func WithSymCacheSize(size int) ModuleOption

type PerfBuf 

type PerfBuf struct {
	*perf.Reader
	// contains filtered or unexported fields
}

func NewPerfBuffer 

func NewPerfBuffer(table *Table, opts *PerfBufOptions) (*PerfBuf, error)

func (*PerfBuf) Close 

func (rb *PerfBuf) Close() error

func (*PerfBuf) Poll 

func (pb *PerfBuf) Poll(timeout time.Duration) (int, error)

type PerfBufLostCallback 

type PerfBufLostCallback func(lost uint64)

type PerfBufOptions 

type PerfBufOptions struct {
	RawCallback   PerfBufRawCallback
	LostCallback  PerfBufLostCallback
	Async         bool
	PerCPUBufSize int
}

type PerfBufRawCallback 

type PerfBufRawCallback func(raw []byte)

type PerfEvent 

type PerfEvent struct {
	// contains filtered or unexported fields
}

func NewPerfEvent 

func NewPerfEvent(prog *ebpf.Program, opts PerfEventOptions) (*PerfEvent, error)

func (*PerfEvent) Close 

func (pe *PerfEvent) Close() error

type PerfEventOptions 

type PerfEventOptions struct {
	Type       uint32
	Config     uint64
	SampleRate uint64
}

PerfEventOptions follow unix.PerfEventAttr

type ResolveSymbolOptions 

type ResolveSymbolOptions struct {
	ShowOffset bool
	ShowModule bool
}

type RingBuf 

type RingBuf struct {
	*ringbuf.Reader
	// contains filtered or unexported fields
}

func NewRingBuf 

func NewRingBuf(table *Table, opts *RingBufOptions) (*RingBuf, error)

func (*RingBuf) Close 

func (rb *RingBuf) Close() error

func (*RingBuf) Poll 

func (rb *RingBuf) Poll(timeout time.Duration) (int, error)

type RingBufCallback 

type RingBufCallback func(raw []byte)

type RingBufOptions 

type RingBufOptions struct {
	Callback RingBufCallback
	Async    bool
}

type StackTable 

type StackTable struct{ *Table }

func NewStackTable 

func NewStackTable(tbl *Table) (*StackTable, error)

func (*StackTable) ClearStackId 

func (t *StackTable) ClearStackId(stackid int64)

func (*StackTable) GetAddrSymbol 

func (t *StackTable) GetAddrSymbol(pid int, addr uint64, opts ResolveSymbolOptions) string

func (*StackTable) GetStackAddr 

func (t *StackTable) GetStackAddr(stackid int64, clear bool) []uint64

type StackTraceT 

type StackTraceT struct {
	InsPtr [MAX_STACK_DEPTH]uint64
}

func (*StackTraceT) ToBytes 

func (st *StackTraceT) ToBytes() []byte

type Table 

type Table struct {
	*ebpf.Map
	// contains filtered or unexported fields
}

func (*Table) TableName 

func (t *Table) TableName() string

func (*Table) TableType 

func (t *Table) TableType() ebpf.MapType

type UpdateFlag 

type UpdateFlag uint32
const (
	UpdateAny UpdateFlag = iota
	// UpdateNoExist creates a new element.
	UpdateNoExist UpdateFlag = 1 << (iota - 1)
	// UpdateExist updates an existing element.
	UpdateExist
	// UpdateLock updates elements under bpf_spin_lock.
	UpdateLock
)

func (UpdateFlag) ToMapUpdateFlag 

func (f UpdateFlag) ToMapUpdateFlag() ebpf.MapUpdateFlags

type UprobeOptions 

type UprobeOptions struct {
	SymbolName    string
	SymbolPattern string
	Pid           int
	Offset        uint64
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
compiler
examples
kprobe
profiler
uprobe
xdp
pkg
byteorder
cpu
exec
logging
logging/logfields
proc
syms
syms/cache
syms/elf
syms/gosym
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.