link

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Mar 5, 2026 License: MIT Imports: 22 Imported by: 653

Documentation

Overview

Package link allows attaching eBPF programs to various kernel hooks.

Index

Examples

Constants

View Source 
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
	KprobeMultiType   = sys.BPF_LINK_TYPE_KPROBE_MULTI
	TCXType           = sys.BPF_LINK_TYPE_TCX
	UprobeMultiType   = sys.BPF_LINK_TYPE_UPROBE_MULTI
	NetfilterType     = sys.BPF_LINK_TYPE_NETFILTER
	NetkitType        = sys.BPF_LINK_TYPE_NETKIT
	StructOpsType     = sys.BPF_LINK_TYPE_STRUCT_OPS
)

Valid link types.

View Source 
const (
	PerfEventUnspecified = sys.BPF_PERF_EVENT_UNSPEC
	PerfEventUprobe      = sys.BPF_PERF_EVENT_UPROBE
	PerfEventUretprobe   = sys.BPF_PERF_EVENT_URETPROBE
	PerfEventKprobe      = sys.BPF_PERF_EVENT_KPROBE
	PerfEventKretprobe   = sys.BPF_PERF_EVENT_KRETPROBE
	PerfEventTracepoint  = sys.BPF_PERF_EVENT_TRACEPOINT
	PerfEventEvent       = sys.BPF_PERF_EVENT_EVENT
)
View Source 
const (
	NetfilterInetPreRouting  = sys.NF_INET_PRE_ROUTING
	NetfilterInetLocalIn     = sys.NF_INET_LOCAL_IN
	NetfilterInetForward     = sys.NF_INET_FORWARD
	NetfilterInetLocalOut    = sys.NF_INET_LOCAL_OUT
	NetfilterInetPostRouting = sys.NF_INET_POST_ROUTING
)
View Source 
const (
	NetfilterProtoUnspec = sys.NFPROTO_UNSPEC
	NetfilterProtoInet   = sys.NFPROTO_INET // Inet applies to both IPv4 and IPv6
	NetfilterProtoIPv4   = sys.NFPROTO_IPV4
	NetfilterProtoARP    = sys.NFPROTO_ARP
	NetfilterProtoNetdev = sys.NFPROTO_NETDEV
	NetfilterProtoBridge = sys.NFPROTO_BRIDGE
	NetfilterProtoIPv6   = sys.NFPROTO_IPV6
)

Variables

View Source 
var (

	// ErrNoSymbol indicates that the given symbol was not found
	// in the ELF symbols table.
	ErrNoSymbol = errors.New("not found")
)
View Source 
var ErrNotSupported = internal.ErrNotSupported

Functions

func AttachSocketFilter added in v0.8.0 

func AttachSocketFilter(conn syscall.Conn, program *ebpf.Program) error

AttachSocketFilter attaches a SocketFilter BPF program to a socket.

func DetachSocketFilter added in v0.8.0 

func DetachSocketFilter(conn syscall.Conn) error

DetachSocketFilter detaches a SocketFilter BPF program from a socket.

func RawAttachProgram 

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 

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.

Types

type Anchor added in v0.13.0 

type Anchor interface {
	// contains filtered or unexported methods
}

Anchor is a reference to a link or program.

It is used to describe where an attachment or detachment should take place for link types which support multiple attachment. 

func AfterLink(target Link) Anchor

After is the position just after target.

func AfterLinkByID added in v0.13.0 

func AfterLinkByID(target ID) Anchor

After is the position just after target.

func AfterProgram added in v0.13.0 

func AfterProgram(target *ebpf.Program) Anchor

After is the position just after target.

func AfterProgramByID added in v0.13.0 

func AfterProgramByID(target ebpf.ProgramID) Anchor

After is the position just after target. 

func BeforeLink(target Link) Anchor

Before is the position just in front of target.

func BeforeLinkByID added in v0.13.0 

func BeforeLinkByID(target ID) Anchor

Before is the position just in front of target.

func BeforeProgram added in v0.13.0 

func BeforeProgram(target *ebpf.Program) Anchor

Before is the position just in front of target.

func BeforeProgramByID added in v0.13.0 

func BeforeProgramByID(target ebpf.ProgramID) Anchor

Before is the position just in front of target. 

func Head() Anchor

Head is the position before all other programs or links.

func ReplaceProgram added in v0.13.0 

func ReplaceProgram(target *ebpf.Program) Anchor

Replace the target itself.

func ReplaceProgramByID added in v0.13.0 

func ReplaceProgramByID(target ebpf.ProgramID) Anchor

Replace the target itself.

func Tail added in v0.13.0 

func Tail() Anchor

Tail is the position after all other programs or links.

type AttachedProgram added in v0.13.0 

type AttachedProgram struct {
	ID ebpf.ProgramID
	// contains filtered or unexported fields
}

func (*AttachedProgram) LinkID added in v0.13.0 

func (ap *AttachedProgram) LinkID() (ID, bool)

LinkID returns the ID associated with the program.

Returns 0, false if the kernel doesn't support retrieving the ID or if the program wasn't attached via a link.

type CgroupInfo added in v0.8.0 

type CgroupInfo struct {
	CgroupId   uint64
	AttachType sys.AttachType
	// contains filtered or unexported fields
}

type CgroupOptions 

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
}

type EventInfo added in v0.21.0 

type EventInfo struct {
	Config uint64
	Type   uint32
	Cookie uint64
}

type Executable added in v0.6.0 

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

Executable defines an executable program on the filesystem.

func OpenExecutable added in v0.6.0 

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 (*Executable) Symbol added in v0.21.0 

func (ex *Executable) Symbol(address uint64) (SymbolOffset, error)

Symbol returns the SymbolOffset that the given address points to. This includes the symbol name and the offset within that symbol.

If no symbol is found for the given address, ErrNoSymbol is returned.

func (*Executable) Uprobe added in v0.6.0 

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.

The returned Link may implement PerfEvent.

func (*Executable) UprobeMulti added in v0.13.0 

func (ex *Executable) UprobeMulti(symbols []string, prog *ebpf.Program, opts *UprobeMultiOptions) (Link, error)

func (*Executable) Uretprobe added in v0.6.0 

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.

The returned Link may implement PerfEvent.

func (*Executable) UretprobeMulti added in v0.13.0 

func (ex *Executable) UretprobeMulti(symbols []string, prog *ebpf.Program, opts *UprobeMultiOptions) (Link, error)

type ID added in v0.2.0 

type ID = sys.LinkID

ID uniquely identifies a BPF link.

type Info added in v0.8.0 

type Info struct {
	Type    Type
	ID      ID
	Program ebpf.ProgramID
	// contains filtered or unexported fields
}

Info contains metadata on a link.

func (Info) Cgroup added in v0.8.0 

func (r Info) Cgroup() *CgroupInfo

Cgroup returns cgroup type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) KprobeMulti added in v0.15.0 

func (r Info) KprobeMulti() *KprobeMultiInfo

KprobeMulti returns kprobe-multi type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) NetNs added in v0.8.0 

func (r Info) NetNs() *NetNsInfo

NetNs returns netns type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) Netfilter added in v0.13.0 

func (r Info) Netfilter() *NetfilterInfo

Netfilter returns netfilter type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) Netkit added in v0.14.0 

func (r Info) Netkit() *NetkitInfo

Netkit returns netkit type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) PerfEvent added in v0.15.0 

func (r Info) PerfEvent() *PerfEventInfo

PerfEvent returns perf-event type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) RawTracepoint added in v0.21.0 

func (r Info) RawTracepoint() *RawTracepointInfo

RawTracepoint returns raw-tracepoint type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) TCX added in v0.13.0 

func (r Info) TCX() *TCXInfo

TCX returns TCX type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) Tracing added in v0.8.0 

func (r Info) Tracing() *TracingInfo

Tracing returns tracing type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) UprobeMulti added in v0.21.0 

func (r Info) UprobeMulti() *UprobeMultiInfo

UprobeMulti returns uprobe-multi type-specific link info.

Returns nil if the type-specific link info isn't available.

func (Info) XDP added in v0.8.0 

func (r Info) XDP() *XDPInfo

XDP returns XDP type-specific link info.

Returns nil if the type-specific link info isn't available.

type Iter 

type Iter struct {
	RawLink
}

Iter represents an attached bpf_iter.

func AttachIter 

func AttachIter(opts IterOptions) (*Iter, error)

AttachIter attaches a BPF seq_file iterator.

func (*Iter) Open 

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 

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
}

type Iterator added in v0.14.0 

type Iterator struct {
	// The ID of the current link. Only valid after a call to Next
	ID ID
	// The current link. Only valid until a call to Next.
	// See Take if you want to retain the link.
	Link Link
	// contains filtered or unexported fields
}

Iterator allows iterating over links attached into the kernel.

func (*Iterator) Close added in v0.14.0 

func (it *Iterator) Close()

func (*Iterator) Err added in v0.14.0 

func (it *Iterator) Err() error

Err returns an error if iteration failed for some reason.

func (*Iterator) Next added in v0.14.0 

func (it *Iterator) Next() bool

Next retrieves the next link.

Returns true if another link was found. Call Iterator.Err after the function returns false.

func (*Iterator) Take added in v0.14.0 

func (it *Iterator) Take() Link

Take the ownership of the current link.

It's the callers responsibility to close the link.

type KprobeInfo added in v0.15.0 

type KprobeInfo struct {
	Address  uint64
	Missed   uint64
	Function string
	Offset   uint32
}

type KprobeMultiAddress added in v0.21.0 

type KprobeMultiAddress struct {
	Address uint64
	Cookie  uint64
}

type KprobeMultiInfo added in v0.15.0 

type KprobeMultiInfo struct {
	// Count is the number of addresses hooked by the kprobe.
	Count  uint32
	Flags  uint32
	Missed uint64
	// contains filtered or unexported fields
}

func (*KprobeMultiInfo) Addresses added in v0.21.0 

func (kpm *KprobeMultiInfo) Addresses() ([]KprobeMultiAddress, bool)

Addresses are the addresses hooked by the kprobe.

type KprobeMultiOptions added in v0.9.2 

type KprobeMultiOptions struct {
	// Symbols takes a list of kernel symbol names to attach an ebpf program to.
	//
	// Mutually exclusive with Addresses.
	Symbols []string

	// Addresses takes a list of kernel symbol addresses in case they can not
	// be referred to by name.
	//
	// Note that only start addresses can be specified, since the fprobe API
	// limits the attach point to the function entry or return.
	//
	// Mutually exclusive with Symbols.
	Addresses []uintptr

	// Cookies specifies arbitrary values that can be fetched from an eBPF
	// program via `bpf_get_attach_cookie()`.
	//
	// If set, its length should be equal to the length of Symbols or Addresses.
	// Each Cookie is assigned to the Symbol or Address specified at the
	// corresponding slice index.
	Cookies []uint64

	// Session must be true when attaching Programs with the
	// [ebpf.AttachTraceKprobeSession] attach type.
	//
	// This makes a Kprobe execute on both function entry and return. The entry
	// program can share a cookie value with the return program and can decide
	// whether the return program gets executed.
	Session bool
}

KprobeMultiOptions defines additional parameters that will be used when opening a KprobeMulti Link.

type KprobeOptions added in v0.9.0 

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
	// Increase the maximum number of concurrent invocations of a kretprobe.
	// Required when tracing some long running functions in the kernel.
	//
	// Warning: this setting forces the use of an outdated kernel API and is
	// not portable across kernel versions. On supported kernels, consider using
	// fexit programs instead, as they don't have this MaxActive limitation.
	RetprobeMaxActive int
	// Prefix used for the event name if the kprobe must be attached using tracefs.
	// The group name will be formatted as `<prefix>_<randomstr>`.
	// The default empty string is equivalent to "ebpf" as the prefix.
	TraceFSPrefix string
}

KprobeOptions defines additional parameters that will be used when loading Kprobes.

type LSMOptions added in v0.8.0 

type LSMOptions struct {
	// Program must be of type LSM with attach type
	// AttachLSMMac.
	Program *ebpf.Program
	// Arbitrary value that can be fetched from an eBPF program
	// via `bpf_get_attach_cookie()`.
	Cookie uint64
}
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

	// Detach the link from its corresponding attachment point.
	//
	// May return an error wrapping ErrNotSupported.
	Detach() error

	// Info returns metadata on a link.
	//
	// May return an error wrapping ErrNotSupported.
	Info() (*Info, error)
	// contains filtered or unexported methods
}

Link represents a Program attached to a BPF hook.

func AttachCgroup 

func AttachCgroup(opts CgroupOptions) (cg Link, err error)

AttachCgroup links a BPF program to a cgroup.

If the running kernel doesn't support bpf_link, attempts to emulate its semantics using the legacy PROG_ATTACH mechanism. If bpf_link is not available, the returned Link will not support pinning to bpffs.

If you need more control over attachment flags or the attachment mechanism used, look at RawAttachProgram and AttachRawLink instead.

func AttachFreplace added in v0.7.0 

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 added in v0.8.0 

func AttachLSM(opts LSMOptions) (Link, error)

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

func AttachNetfilter added in v0.13.0 

func AttachNetfilter(opts NetfilterOptions) (Link, error)

AttachNetfilter links a netfilter BPF program to a netfilter hook.

func AttachNetkit added in v0.14.0 

func AttachNetkit(opts NetkitOptions) (Link, error)

func AttachRawTracepoint 

func AttachRawTracepoint(opts RawTracepointOptions) (Link, error)

AttachRawTracepoint links a BPF program to a raw_tracepoint.

Requires at least Linux 4.17.

func AttachStructOps added in v0.21.0 

func AttachStructOps(opts StructOpsOptions) (Link, error)

AttachStructOps attaches a struct_ops map (created from a ".struct_ops.link" section) to its kernel subsystem via a BPF link.

func AttachTCX added in v0.13.0 

func AttachTCX(opts TCXOptions) (Link, error)

func AttachTracing added in v0.8.0 

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 added in v0.8.0 

func AttachXDP(opts XDPOptions) (Link, error)

AttachXDP links an XDP BPF program to an XDP hook.

func Kprobe added in v0.5.0 

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.

If attaching to symbol fails, automatically retries with the running platform's syscall prefix (e.g. __x64_) to support attaching to syscalls in a portable fashion.

On kernels 6.11 and later, setting a kprobe on a nonexistent symbol using tracefs incorrectly returns unix.EINVAL instead of os.ErrNotExist.

The returned Link may implement PerfEvent.

func KprobeMulti added in v0.9.2 

func KprobeMulti(prog *ebpf.Program, opts KprobeMultiOptions) (Link, error)

KprobeMulti attaches the given eBPF program to the entry point of a given set of kernel symbols.

The difference with Kprobe() is that multi-kprobe accomplishes this in a single system call, making it significantly faster than attaching many probes one at a time.

Requires at least Linux 5.18.

func Kretprobe added in v0.5.0 

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.

If attaching to symbol fails, automatically retries with the running platform's syscall prefix (e.g. __x64_) to support attaching to syscalls in a portable fashion.

On kernels 5.10 and earlier, setting a kretprobe on a nonexistent symbol incorrectly returns unix.EINVAL instead of os.ErrNotExist.

The returned Link may implement PerfEvent.

func KretprobeMulti added in v0.9.2 

func KretprobeMulti(prog *ebpf.Program, opts KprobeMultiOptions) (Link, error)

KretprobeMulti attaches the given eBPF program to the return point of a given set of kernel symbols.

The difference with Kretprobe() is that multi-kprobe accomplishes this in a single system call, making it significantly faster than attaching many probes one at a time.

Requires at least Linux 5.18. 

func LoadPinnedLink(fileName string, opts *ebpf.LoadPinOptions) (Link, error)

LoadPinnedLink loads a Link from a pin (file) on the BPF virtual filesystem.

Requires at least Linux 5.7.

func NewFromFD added in v0.14.0 

func NewFromFD(fd int) (Link, error)

NewFromFD creates a link from a raw fd.

You should not use fd after calling this function.

func NewFromID added in v0.14.0 

func NewFromID(id ID) (Link, error)

NewFromID returns the link associated with the given id.

Returns ErrNotExist if there is no link with the given id.

func Tracepoint added in v0.5.0 

func Tracepoint(group, name string, prog *ebpf.Program, opts *TracepointOptions) (Link,