package link

import "github.com/cilium/ebpf/link"

Package link allows attaching eBPF programs to various kernel hooks.

Index

Examples

Variables 

var (

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

Functions

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 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 Executable 

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

Executable defines an executable program on the filesystem.

func OpenExecutable 

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) Uprobe 

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})

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 (*Executable) Uretprobe 

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})

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. 

type FreplaceLink struct {
	RawLink
}

func AttachFreplace 

func AttachFreplace(targetProg *ebpf.Program, name string, prog *ebpf.Program) (*FreplaceLink, 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 LoadPinnedFreplace 

func LoadPinnedFreplace(fileName string, opts *ebpf.LoadPinOptions) (*FreplaceLink, error)

LoadPinnedFreplace loads a pinned iterator from a bpffs.

func (*FreplaceLink) Update 

func (f *FreplaceLink) Update(new *ebpf.Program) error

Update implements the Link interface.

type ID 

type ID uint32

ID uniquely identifies a BPF link.

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 LoadPinnedIter 

func LoadPinnedIter(fileName string, opts *ebpf.LoadPinOptions) (*Iter, error)

LoadPinnedIter loads a pinned iterator from a bpffs.

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 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
	// contains filtered or unexported methods
}

Link represents a Program attached to a BPF hook.

func AttachCgroup 

func AttachCgroup(opts CgroupOptions) (Link, error)

AttachCgroup links a BPF program to a cgroup.

func AttachRawTracepoint 

func AttachRawTracepoint(opts RawTracepointOptions) (Link, error)

AttachRawTracepoint links a BPF program to a raw_tracepoint.

Requires at least Linux 4.17.

func Kprobe 

func Kprobe(symbol string, prog *ebpf.Program) (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)

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 

func Kretprobe(symbol string, prog *ebpf.Program) (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)

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 LoadPinnedCgroup 

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

LoadPinnedCgroup loads a pinned cgroup from a bpffs.

func Tracepoint 

func Tracepoint(group, name string, prog *ebpf.Program) (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)

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 

type NetNsInfo struct {
	RawLinkInfo
}

NetNsInfo contains metadata about a network namespace link. 

type NetNsLink struct {
	*RawLink
}

NetNsLink is a program attached to a network namespace.

func AttachNetNs 

func AttachNetNs(ns int, prog *ebpf.Program) (*NetNsLink, error)

AttachNetNs attaches a program to a network namespace.

Example

Code: 

{
	prog, err := createSkLookupProgram()
	if err != nil {
		panic(err)
	}
	defer prog.Close()

	// This can be a path to another netns as well.
	netns, err := os.Open("/proc/self/ns/net")
	if err != nil {
		panic(err)
	}
	defer netns.Close()

	link, err := AttachNetNs(int(netns.Fd()), prog)
	if err != nil {
		panic(err)
	}

	// The socket lookup program is now active until Close().
	link.Close()
}

func LoadPinnedNetNs 

func LoadPinnedNetNs(fileName string, opts *ebpf.LoadPinOptions) (*NetNsLink, error)

LoadPinnedNetNs loads a network namespace link from bpffs.

func (*NetNsLink) Info 

func (nns *NetNsLink) Info() (*NetNsInfo, error)

Info returns information about the link.

type RawAttachProgramOptions 

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 

type RawDetachProgramOptions struct {
	Target  int
	Program *ebpf.Program
	Attach  ebpf.AttachType
}
type RawLink struct {
	// contains filtered or unexported fields
}

RawLink is the low-level API to bpf_link.

You should consider using the higher level interfaces in this package instead. 

func AttachRawLink(opts RawLinkOptions) (*RawLink, error)

AttachRawLink creates a raw link. 

func LoadPinnedRawLink(fileName string, linkType Type, opts *ebpf.LoadPinOptions) (*RawLink, error)

LoadPinnedRawLink loads a persisted link from a bpffs.

Returns an error if the pinned link type doesn't match linkType. Pass UnspecifiedType to disable this behaviour.

func (*RawLink) Close 

func (l *RawLink) Close() error

Close breaks the link.

Use Pin if you want to make the link persistent.

func (*RawLink) FD 

func (l *RawLink) FD() int

FD returns the raw file descriptor.

func (*RawLink) Info 

func (l *RawLink) Info() (*RawLinkInfo, error)

Info returns metadata about the link.

func (*RawLink) Pin 

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 (*RawLink) Unpin 

func (l *RawLink) Unpin() error

Unpin implements the Link interface.

func (*RawLink) Update 

func (l *RawLink) Update(new *ebpf.Program) error

Update implements the Link interface.

func (*RawLink) UpdateArgs 

func (l *RawLink) UpdateArgs(opts RawLinkUpdateOptions) error

UpdateArgs updates a link based on args.

type RawLinkInfo 

type RawLinkInfo struct {
	Type    Type
	ID      ID
	Program ebpf.ProgramID
}

RawLinkInfo contains metadata on a link.

type RawLinkOptions 

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
}

RawLinkOptions control the creation of a raw link.

type RawLinkUpdateOptions 

type RawLinkUpdateOptions struct {
	New   *ebpf.Program
	Old   *ebpf.Program
	Flags uint32
}

RawLinkUpdateOptions control the behaviour of RawLink.UpdateArgs.

type RawTracepointOptions 

type RawTracepointOptions struct {
	// Tracepoint name.
	Name string
	// Program must be of type RawTracepoint*
	Program *ebpf.Program
}

type Type 

type Type uint32

Type is the kind of link. 

const (
	UnspecifiedType Type = iota
	RawTracepointType
	TracingType
	CgroupType
	IterType
	NetNsType
	XDPType
)

Valid link types.

Equivalent to enum bpf_link_type.

type UprobeOptions 

type UprobeOptions struct {
	// Symbol offset. Must be provided in case of external symbols (shared libs).
	// If set, overrides the offset eventually parsed from the executable.
	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
}

UprobeOptions defines additional parameters that will be used when loading Uprobes.

Source Files

cgroup.go doc.go freplace.go iter.go kprobe.go link.go netns.go perf_event.go platform.go program.go raw_tracepoint.go syscalls.go tracepoint.go uprobe.go

Version
v0.7.0
Published
Oct 8, 2021
Platform
darwin/amd64
Imports
19 packages
Last checked
2 hours ago –

Tools for package owners.