link

package
v0.0.0-...-a55c778 Latest Latest
Warning

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

 Go to latest Published: Jul 6, 2024 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package link allows attaching gBPF 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
)

Valid link types.

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 

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

AttachSocketFilter attaches a SocketFilter BPF program to a socket.

func DetachSocketFilter 

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 

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 

func AfterLinkByID(target ID) Anchor

After is the position just after target.

func AfterProgram 

func AfterProgram(target *gbpf.Program) Anchor

After is the position just after target.

func AfterProgramByID 

func AfterProgramByID(target gbpf.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 

func BeforeLinkByID(target ID) Anchor

Before is the position just in front of target.

func BeforeProgram 

func BeforeProgram(target *gbpf.Program) Anchor

Before is the position just in front of target.

func BeforeProgramByID 

func BeforeProgramByID(target gbpf.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 

func ReplaceProgram(target *gbpf.Program) Anchor

Replace the target itself.

func ReplaceProgramByID 

func ReplaceProgramByID(target gbpf.ProgramID) Anchor

Replace the target itself.

func Tail 

func Tail() Anchor

Tail is the position after all other programs or links.

type AttachedProgram 

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

func (*AttachedProgram) LinkID 

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. See QueryResult.HaveLinkInfo if you need to tell the two apart.

type CgroupInfo 

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 gbpf.AttachType
	// Program must be of type CGroup*, and the attach type must match Attach.
	Program *gbpf.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 *gbpf.Program, opts *UprobeOptions) (Link, error)

Uprobe attaches the given gBPF 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 

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

func (*Executable) Uretprobe 

func (ex *Executable) Uretprobe(symbol string, prog *gbpf.Program, opts *UprobeOptions) (Link, error)

Uretprobe attaches the given gBPF 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 

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

type ID 

type ID = sys.LinkID

ID uniquely identifies a BPF link.

type Info 

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

Info contains metadata on a link.

func (Info) Cgroup 

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 

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 

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 

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 

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 

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

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 

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

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 *gbpf.Program

	// Map specifies the target map for bpf_map_elem and sockmap iterators.
	// It may be nil.
	Map *gbpf.Map
}

type Iterator 

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 

func (it *Iterator) Close()

func (*Iterator) Err 

func (it *Iterator) Err() error

Err returns an error if iteration failed for some reason.

func (*Iterator) Next 

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 

func (it *Iterator) Take() Link

Take the ownership of the current link.

It's the callers responsibility to close the link.

type KprobeInfo 

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

func (*KprobeInfo) Address 

func (kp *KprobeInfo) Address() (uint64, bool)

func (*KprobeInfo) Missed 

func (kp *KprobeInfo) Missed() (uint64, bool)

type KprobeMultiInfo 

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

func (*KprobeMultiInfo) AddressCount 

func (kpm *KprobeMultiInfo) AddressCount() (uint32, bool)

AddressCount is the number of addresses hooked by the kprobe.

func (*KprobeMultiInfo) Flags 

func (kpm *KprobeMultiInfo) Flags() (uint32, bool)

func (*KprobeMultiInfo) Missed 

func (kpm *KprobeMultiInfo) Missed() (uint64, bool)

type KprobeMultiOptions 

type KprobeMultiOptions struct {
	// Symbols takes a list of kernel symbol names to attach an gbpf 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 gBPF
	// 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
}

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

type KprobeOptions 

type KprobeOptions struct {
	// Arbitrary value that can be fetched from an gBPF 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.
	//
	// Deprecated: this setting forces the use of an outdated kernel API and is not portable
	// across kernel versions.
	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 "gbpf" as the prefix.
	TraceFSPrefix string
}

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

type LSMOptions 

type LSMOptions struct {
	// Program must be of type LSM with attach type
	// AttachLSMMac.
	Program *gbpf.Program
	// Arbitrary value that can be fetched from an gBPF 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(*gbpf.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
}

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 

func AttachFreplace(targetProg *gbpf.Program, name string, prog *gbpf.Program) (Link, error)

AttachFreplace attaches the given gBPF 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 

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 

func AttachNetfilter(opts NetfilterOptions) (Link, error)

AttachNetfilter links a netfilter BPF program to a netfilter hook.

func AttachNetkit 

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 AttachTCX 

func AttachTCX(opts TCXOptions) (Link, error)

func AttachTracing 

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 

func AttachXDP(opts XDPOptions) (Link, error)

AttachXDP links an XDP BPF program to an XDP hook.

func Kprobe 

func Kprobe(symbol string, prog *gbpf.Program, opts *KprobeOptions) (Link, error)

Kprobe attaches the given gBPF 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.

The returned Link may implement PerfEvent.

func KprobeMulti 

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

KprobeMulti attaches the given gBPF 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 

func Kretprobe(symbol string, prog *gbpf.Program, opts *KprobeOptions) (Link, error)

Kretprobe attaches the given gBPF 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 

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

KretprobeMulti attaches the given gBPF 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 *gbpf.LoadPinOptions) (Link, error)

LoadPinnedLink loads a link that was persisted into a bpffs.

func NewFromFD 

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 

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 NewLinkFromFD deprecated 

func NewLinkFromFD(fd int) (Link, error)

NewLinkFromFD creates a link from a raw fd.

Deprecated: use NewFromFD instead.

func Tracepoint 

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

Tracepoint attaches the given gBPF program to the tracepoint with the given group and name. See /sys/kernel/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 gBPF programs to syscalls (sys_enter_*/sys_exit_*) is only possible as of kernel 4.14 (commit cf5f5ce).

The returned Link may implement PerfEvent.

type NetNsInfo 

type NetNsInfo struct {
	NetnsIno   uint32
	AttachType sys.AttachType
}
type NetNsLink struct {
	RawLink
}

NetNsLink is a program attached to a network namespace.

func AttachNetNs 

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

AttachNetNs attaches a program to a network namespace.

Example 
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()

Output:

func (*NetNsLink) Info 

func (ns *NetNsLink) Info() (*Info, error)

type NetfilterAttachFlags 

type NetfilterAttachFlags uint32
const NetfilterIPDefrag NetfilterAttachFlags = 0 // Enable IP packet defragmentation

type NetfilterInfo 

type NetfilterInfo struct {
	Pf       uint32
	Hooknum  uint32
	Priority int32
	Flags    uint32
}

type NetfilterOptions 

type NetfilterOptions struct {
	// Program must be a netfilter BPF program.
	Program *gbpf.Program
	// The protocol family.
	ProtocolFamily uint32
	// The number of the hook you are interested in.
	HookNumber uint32
	// Priority within hook
	Priority int32
	// Extra link flags
	Flags uint32
	// Netfilter flags
	NetfilterFlags NetfilterAttachFlags
}

type NetkitInfo 

type NetkitInfo struct {
	Ifindex    uint32
	AttachType sys.AttachType
}

type NetkitOptions 

type NetkitOptions struct {
	// Index of the interface to attach to.
	Interface int
	// Program to attach.
	Program *gbpf.Program
	// One of the AttachNetkit* constants.
	Attach gbpf.AttachType
	// Attach relative to an anchor. Optional.
	Anchor Anchor
	// Only attach if the expected revision matches.
	ExpectedRevision uint64
	// Flags control the attach behaviour. Specify an Anchor instead of
	// F_LINK, F_ID, F_BEFORE, F_AFTER and R_REPLACE. Optional.
	Flags uint32
}

type PerfEvent 

type PerfEvent interface {
	// PerfEvent returns a file for the underlying perf event.
	//
	// It is the callers responsibility to close the returned file.
	//
	// Making changes to the associated perf event lead to
	// undefined behaviour.
	PerfEvent() (*os.File, error)
}

PerfEvent is implemented by some Link types which use a perf event under the hood.

type PerfEventInfo 

type PerfEventInfo struct {
	Type sys.PerfEventType
	// contains filtered or unexported fields
}

func (*PerfEventInfo) Kprobe 

func (r *PerfEventInfo) Kprobe() *KprobeInfo

type QueryOptions 

type QueryOptions struct {
	// Target to query. This is usually a file descriptor but may refer to
	// something else based on the attach type.
	Target int
	// Attach specifies the AttachType of the programs queried for
	Attach gbpf.AttachType
	// QueryFlags are flags for BPF_PROG_QUERY, e.g. BPF_F_QUERY_EFFECTIVE
	QueryFlags uint32
}

QueryOptions defines additional parameters when querying for programs.

type QueryResult 

type QueryResult struct {
	// List of attached programs.
	Programs []AttachedProgram

	// Incremented by one every time the set of attached programs changes.
	// May be zero if not supported by the [gbpf.AttachType].
	Revision uint64
}

QueryResult describes which programs and links are active.

func QueryPrograms 

func QueryPrograms(opts QueryOptions) (*QueryResult, error)

QueryPrograms retrieves a list of programs for the given AttachType.

Returns a slice of attached programs, which may be empty. revision counts how many times the set of attached programs has changed and may be zero if not supported by the gbpf.AttachType. Returns ErrNotSupportd on a kernel without BPF_PROG_QUERY

func (*QueryResult) HaveLinkInfo 

func (qr *QueryResult) HaveLinkInfo() bool

HaveLinkInfo returns true if the kernel supports querying link information for a particular gbpf.AttachType.

type RawAttachProgramOptions 

type RawAttachProgramOptions struct {
	// Target to query. This is usually a file descriptor but may refer to
	// something else based on the attach type.
	Target int
	// Program to attach.
	Program *gbpf.Program
	// Attach must match the attach type of Program.
	Attach gbpf.AttachType
	// Attach relative to an anchor. Optional.
	Anchor Anchor
	// Flags control the attach behaviour. Specify an Anchor instead of
	// F_LINK, F_ID, F_BEFORE, F_AFTER and F_REPLACE. Optional.
	Flags uint32
	// Only attach if the internal revision matches the given value.
	ExpectedRevision uint64
}

type RawDetachProgramOptions 

type RawDetachProgramOptions RawAttachProgramOptions
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 (*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() (*Info, error)

Info returns metadata about the link.

Linktype specific metadata is not included and can be retrieved via the linktype specific Info() method.

func (*RawLink) IsPinned 

func (l *RawLink) IsPinned() bool

IsPinned returns true if the Link has a non-empty pinned path.

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 *gbpf.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 RawLinkOptions 

type RawLinkOptions struct {
	// File descriptor to attach to. This differs for each attach type.
	Target int
	// Program to attach.
	Program *gbpf.Program
	// Attach must match the attach type of Program.
	Attach gbpf.AttachType
	// BTF is the BTF of the attachment target.
	BTF btf.TypeID
	// Flags control the attach behaviour.
	Flags uint32
}

RawLinkOptions control the creation of a raw link.

type RawLinkUpdateOptions 

type RawLinkUpdateOptions struct {
	New   *gbpf.Program
	Old   *gbpf.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 *gbpf.Program
}

type TCXInfo 

type TCXInfo struct {
	Ifindex    uint32
	AttachType sys.AttachType
}

type TCXOptions 

type TCXOptions struct {
	// Index of the interface to attach to.
	Interface int
	// Program to attach.
	Program *gbpf.Program
	// One of the AttachTCX* constants.
	Attach gbpf.AttachType
	// Attach relative to an anchor. Optional.
	Anchor Anchor
	// Only attach if the expected revision matches.
	ExpectedRevision uint64
	// Flags control the attach behaviour. Specify an Anchor instead of
	// F_LINK, F_ID, F_BEFORE, F_AFTER and R_REPLACE. Optional.
	Flags uint32
}

type TracepointOptions 

type TracepointOptions struct {
	// Arbitrary value that can be fetched from an gBPF program
	// via `bpf_get_attach_cookie()`.
	//
	// Needs kernel 5.15+.
	Cookie uint64
}

TracepointOptions defines additional parameters that will be used when loading Tracepoints.

type TracingInfo 

type TracingInfo struct {
	AttachType  sys.AttachType
	TargetObjId uint32
	TargetBtfId sys.TypeID
}

type TracingOptions 

type TracingOptions struct {
	// Program must be of type Tracing with attach type
	// AttachTraceFEntry/AttachTraceFExit/AttachModifyReturn or
	// AttachTraceRawTp.
	Program *gbpf.Program
	// Program attach type. Can be one of:
	// 	- AttachTraceFEntry
	// 	- AttachTraceFExit
	// 	- AttachModifyReturn
	// 	- AttachTraceRawTp
	// This field is optional.
	AttachType gbpf.AttachType
	// Arbitrary value that can be fetched from an gBPF program
	// via `bpf_get_attach_cookie()`.
	Cookie uint64
}

type Type 

type Type = sys.LinkType

Type is the kind of link.

type UprobeMultiOptions 

type UprobeMultiOptions struct {
	// Symbol addresses. If set, overrides the addresses eventually parsed from
	// the executable. Mutually exclusive with UprobeMulti's symbols argument.
	Addresses []uint64

	// Offsets into functions provided by UprobeMulti's symbols argument.
	// For example: to set uprobes to main+5 and _start+10, call UprobeMulti
	// with:
	//     symbols: "main", "_start"
	//     opt.Offsets: 5, 10
	Offsets []uint64

	// Optional list of associated ref counter offsets.
	RefCtrOffsets []uint64

	// Optional list of associated BPF cookies.
	Cookies []uint64

	// Only set the uprobe_multi link on the given process ID, zero PID means
	// system-wide.
	PID uint32
}

UprobeMultiOptions defines additional parameters that will be used when opening a UprobeMulti Link.

type UprobeOptions 

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 gBPF program
	// via `bpf_get_attach_cookie()`.
	//
	// Needs kernel 5.15+.
	Cookie uint64
	// Prefix used for the event name if the uprobe must be attached using tracefs.
	// The group name will be formatted as `<prefix>_<randomstr>`.
	// The default empty string is equivalent to "gbpf" as the prefix.
	TraceFSPrefix string
}

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

type XDPAttachFlags 

type XDPAttachFlags uint32

XDPAttachFlags represents how XDP program will be attached to interface. 

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 

type XDPInfo struct {
	Ifindex uint32
}

type XDPOptions 

type XDPOptions struct {
	// Program must be an XDP BPF program.
	Program *gbpf.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
}

Source Files

View all Source files

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.