Valid link types.
const (
UnspecifiedType = sys.BPF_LINK_TYPE_UNSPEC
RawTracepointType = sys.BPF_LINK_TYPE_RAW_TRACEPOINT
TracingType = sys.BPF_LINK_TYPE_TRACING
CgroupType = sys.BPF_LINK_TYPE_CGROUP
IterType = sys.BPF_LINK_TYPE_ITER
NetNsType = sys.BPF_LINK_TYPE_NETNS
XDPType = sys.BPF_LINK_TYPE_XDP
PerfEventType = sys.BPF_LINK_TYPE_PERF_EVENT
)
var (
// ErrNoSymbol indicates that the given symbol was not found
// in the ELF symbols table.
ErrNoSymbol = errors.New("not found")
)
var ErrNotSupported = internal.ErrNotSupported
func AttachSocketFilter(conn syscall.Conn, program *ebpf.Program) error
AttachSocketFilter attaches a SocketFilter BPF program to a socket.
func DetachSocketFilter(conn syscall.Conn) error
DetachSocketFilter detaches a SocketFilter BPF program from a socket.
func RawAttachProgram(opts RawAttachProgramOptions) error
RawAttachProgram is a low level wrapper around BPF_PROG_ATTACH.
You should use one of the higher level abstractions available in this package if possible.
func RawDetachProgram(opts RawDetachProgramOptions) error
RawDetachProgram is a low level wrapper around BPF_PROG_DETACH.
You should use one of the higher level abstractions available in this package if possible.
type CgroupInfo sys.CgroupLinkInfo
type CgroupOptions struct {
// Path to a cgroupv2 folder.
Path string
// One of the AttachCgroup* constants
Attach ebpf.AttachType
// Program must be of type CGroup*, and the attach type must match Attach.
Program *ebpf.Program
}
Executable defines an executable program on the filesystem.
type Executable struct {
// contains filtered or unexported fields
}
func OpenExecutable(path string) (*Executable, error)
To open a new Executable, use:
OpenExecutable("/bin/bash")
The returned value can then be used to open Uprobe(s).
func (ex *Executable) Uprobe(symbol string, prog *ebpf.Program, opts *UprobeOptions) (Link, error)
Uprobe 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():
ex, _ = OpenExecutable("/bin/bash")
ex.Uprobe("main", prog, nil)
When using symbols which belongs to shared libraries, an offset must be provided via options:
up, err := ex.Uprobe("main", prog, &UprobeOptions{Offset: 0x123})
Note: Setting the Offset field in the options supersedes the symbol's offset.
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 (ex *Executable) Uretprobe(symbol string, prog *ebpf.Program, opts *UprobeOptions) (Link, error)
Uretprobe attaches the given eBPF program to a perf event that fires right before the given symbol exits. For example, /bin/bash::main():
ex, _ = OpenExecutable("/bin/bash")
ex.Uretprobe("main", prog, nil)
When using symbols which belongs to shared libraries, an offset must be provided via options:
up, err := ex.Uretprobe("main", prog, &UprobeOptions{Offset: 0x123})
Note: Setting the Offset field in the options supersedes the symbol's offset.
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.
ID uniquely identifies a BPF link.
type ID = sys.LinkID
Info contains metadata on a link.
type Info struct {
Type Type
ID ID
Program ebpf.ProgramID
// contains filtered or unexported fields
}
func (r Info) Cgroup() *CgroupInfo
Cgroup returns cgroup type-specific link info.
Returns nil if the type-specific link info isn't available.
func (r Info) NetNs() *NetNsInfo
NetNs returns netns type-specific link info.
Returns nil if the type-specific link info isn't available.
func (r Info) Tracing() *TracingInfo
Tracing returns tracing type-specific link info.
Returns nil if the type-specific link info isn't available.
func (r Info) XDP() *XDPInfo
ExtraNetNs returns XDP type-specific link info.
Returns nil if the type-specific link info isn't available.
Iter represents an attached bpf_iter.
type Iter struct {
RawLink
}
func AttachIter(opts IterOptions) (*Iter, error)
AttachIter attaches a BPF seq_file iterator.
func (it *Iter) Open() (io.ReadCloser, error)
Open creates a new instance of the iterator.
Reading from the returned reader triggers the BPF program.
type IterOptions struct {
// Program must be of type Tracing with attach type
// AttachTraceIter. The kind of iterator to attach to is
// determined at load time via the AttachTo field.
//
// AttachTo requires the kernel to include BTF of itself,
// and it to be compiled with a recent pahole (>= 1.16).
Program *ebpf.Program
// Map specifies the target map for bpf_map_elem and sockmap iterators.
// It may be nil.
Map *ebpf.Map
}
KprobeOptions defines additional parameters that will be used when loading Kprobes.
type KprobeOptions struct {
// Arbitrary value that can be fetched from an eBPF program
// via `bpf_get_attach_cookie()`.
//
// Needs kernel 5.15+.
Cookie uint64
// Offset of the kprobe relative to the traced symbol.
// Can be used to insert kprobes at arbitrary offsets in kernel functions,
// e.g. in places where functions have been inlined.
Offset uint64
}
type LSMOptions struct {
// Program must be of type LSM with attach type
// AttachLSMMac.
Program *ebpf.Program
}
Link represents a Program attached to a BPF hook.
type Link interface {
// Replace the current program with a new program.
//
// Passing a nil program is an error. May return an error wrapping ErrNotSupported.
Update(*ebpf.Program) error
// Persist a link by pinning it into a bpffs.
//
// May return an error wrapping ErrNotSupported.
Pin(string) error
// Undo a previous call to Pin.
//
// May return an error wrapping ErrNotSupported.
Unpin() error
// Close frees resources.
//
// The link will be broken unless it has been successfully pinned.
// A link may continue past the lifetime of the process if Close is
// not called.
Close() error
// Info returns metadata on a link.
//
// May return an error wrapping ErrNotSupported.
Info() (*Info, error)
// contains filtered or unexported methods
}
func AttachCgroup(opts CgroupOptions) (Link, error)
AttachCgroup links a BPF program to a cgroup.
func AttachFreplace(targetProg *ebpf.Program, name string, prog *ebpf.Program) (Link, error)
AttachFreplace attaches the given eBPF program to the function it replaces.
The program and name can either be provided at link time, or can be provided at program load time. If they were provided at load time, they should be nil and empty respectively here, as they will be ignored by the kernel. Examples:
AttachFreplace(dispatcher, "function", replacement) AttachFreplace(nil, "", replacement)
func AttachLSM(opts LSMOptions) (Link, error)
AttachLSM links a Linux security module (LSM) BPF Program to a BPF hook defined in kernel modules.
func AttachRawTracepoint(opts RawTracepointOptions) (Link, error)
AttachRawTracepoint links a BPF program to a raw_tracepoint.
Requires at least Linux 4.17.
func AttachTracing(opts TracingOptions) (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 AttachXDP(opts XDPOptions) (Link, error)
AttachXDP links an XDP BPF program to an XDP hook.
func Kprobe(symbol string, prog *ebpf.Program, opts *KprobeOptions) (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():
kp, err := Kprobe("printk", prog, nil)
Losing the reference to the resulting Link (kp) will close the Kprobe and prevent further execution of prog. The Link must be Closed during program shutdown to avoid leaking system resources.
func Kretprobe(symbol string, prog *ebpf.Program, opts *KprobeOptions) (Link, error)
Kretprobe 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)
Losing the reference to the resulting Link (kp) will close the Kretprobe and prevent further execution of prog. The Link must be Closed during program shutdown to avoid leaking system resources.
func LoadPinnedLink(fileName string, opts *ebpf.LoadPinOptions) (Link, error)
LoadPinnedLink loads a link that was persisted into a bpffs.
func Tracepoint(group, name string, prog *ebpf.Program, opts *TracepointOptions) (Link, error)
Tracepoint attaches the given eBPF program to the tracepoint with the given group and name. See /sys/kernel/debug/tracing/events to find available tracepoints. The top-level directory is the group, the event's subdirectory is the name. Example:
tp, err := Tracepoint("syscalls", "sys_enter_fork", prog, nil)
Losing the reference to the resulting Link (tp) will close the Tracepoint and prevent further execution of prog. The Link must be Closed during program shutdown to avoid leaking system resources.
Note that attaching eBPF programs to syscalls (sys_enter_*/sys_exit_*) is only possible as of kernel 4.14 (commit cf5f5ce).
type NetNsInfo sys.NetNsLinkInfo
NetNsLink is a program attached to a network namespace.
type NetNsLink struct {
RawLink
}
func AttachNetNs(ns int, prog *ebpf.Program) (*NetNsLink, error)
AttachNetNs attaches a program to a network namespace.
▹ Example
type RawAttachProgramOptions struct {
// File descriptor to attach to. This differs for each attach type.
Target int
// Program to attach.
Program *ebpf.Program
// Program to replace (cgroups).
Replace *ebpf.Program
// Attach must match the attach type of Program (and Replace).
Attach ebpf.AttachType
// Flags control the attach behaviour. This differs for each attach type.
Flags uint32
}
type RawDetachProgramOptions struct {
Target int
Program *ebpf.Program
Attach ebpf.AttachType
}
RawLink is the low-level API to bpf_link.
You should consider using the higher level interfaces in this package instead.
type RawLink struct {
// contains filtered or unexported fields
}
func AttachRawLink(opts RawLinkOptions) (*RawLink, error)
AttachRawLink creates a raw link.
func (l *RawLink) Close() error
Close breaks the link.
Use Pin if you want to make the link persistent.
func (l *RawLink) FD() int
FD returns the raw file descriptor.
func (l *RawLink) Info() (*Info, error)
Info returns metadata about the link.
func (l *RawLink) Pin(fileName string) error
Pin persists a link past the lifetime of the process.
Calling Close on a pinned Link will not break the link until the pin is removed.
func (l *RawLink) Unpin() error
Unpin implements the Link interface.
func (l *RawLink) Update(new *ebpf.Program) error
Update implements the Link interface.
func (l *RawLink) UpdateArgs(opts RawLinkUpdateOptions) error
UpdateArgs updates a link based on args.
RawLinkOptions control the creation of a raw link.
type RawLinkOptions struct {
// File descriptor to attach to. This differs for each attach type.
Target int
// Program to attach.
Program *ebpf.Program
// Attach must match the attach type of Program.
Attach ebpf.AttachType
// BTF is the BTF of the attachment target.
BTF btf.TypeID
// Flags control the attach behaviour.
Flags uint32
}
RawLinkUpdateOptions control the behaviour of RawLink.UpdateArgs.
type RawLinkUpdateOptions struct {
New *ebpf.Program
Old *ebpf.Program
Flags uint32
}
type RawTracepointOptions struct {
// Tracepoint name.
Name string
// Program must be of type RawTracepoint*
Program *ebpf.Program
}
TracepointOptions defines additional parameters that will be used when loading Tracepoints.
type TracepointOptions struct {
// Arbitrary value that can be fetched from an eBPF program
// via `bpf_get_attach_cookie()`.
//
// Needs kernel 5.15+.
Cookie uint64
}
type TracingInfo sys.TracingLinkInfo
type TracingOptions struct {
// Program must be of type Tracing with attach type
// AttachTraceFEntry/AttachTraceFExit/AttachModifyReturn or
// AttachTraceRawTp.
Program *ebpf.Program
}
Type is the kind of link.
type Type = sys.LinkType
UprobeOptions defines additional parameters that will be used when loading Uprobes.
type UprobeOptions struct {
// Symbol address. Must be provided in case of external symbols (shared libs).
// If set, overrides the address eventually parsed from the executable.
Address uint64
// The offset relative to given symbol. Useful when tracing an arbitrary point
// inside the frame of given symbol.
//
// Note: this field changed from being an absolute offset to being relative
// to Address.
Offset uint64
// Only set the uprobe on the given process ID. Useful when tracing
// shared library calls or programs that have many running instances.
PID int
// Automatically manage SDT reference counts (semaphores).
//
// If this field is set, the Kernel will increment/decrement the
// semaphore located in the process memory at the provided address on
// probe attach/detach.
//
// See also:
// sourceware.org/systemtap/wiki/UserSpaceProbeImplementation (Semaphore Handling)
// github.com/torvalds/linux/commit/1cc33161a83d
// github.com/torvalds/linux/commit/a6ca88b241d5
RefCtrOffset uint64
// Arbitrary value that can be fetched from an eBPF program
// via `bpf_get_attach_cookie()`.
//
// Needs kernel 5.15+.
Cookie uint64
}
XDPAttachFlags represents how XDP program will be attached to interface.
type XDPAttachFlags uint32
const (
// XDPGenericMode (SKB) links XDP BPF program for drivers which do
// not yet support native XDP.
XDPGenericMode XDPAttachFlags = 1 << (iota + 1)
// XDPDriverMode links XDP BPF program into the driver’s receive path.
XDPDriverMode
// XDPOffloadMode offloads the entire XDP BPF program into hardware.
XDPOffloadMode
)
type XDPInfo sys.XDPLinkInfo
type XDPOptions struct {
// Program must be an XDP BPF program.
Program *ebpf.Program
// Interface is the interface index to attach program to.
Interface int
// Flags is one of XDPAttachFlags (optional).
//
// Only one XDP mode should be set, without flag defaults
// to driver/generic mode (best effort).
Flags XDPAttachFlags
}