# README
eBPF
ebpf-go is a pure Go library that provides utilities for loading, compiling, and debugging eBPF programs. It has minimal external dependencies and is intended to be used in long running processes.
See ebpf.io for complementary projects from the wider eBPF ecosystem.
Getting Started
Please take a look at our Getting Started guide.
Contributions are highly encouraged, as they highlight certain use cases of eBPF and the library, and help shape the future of the project.
Getting Help
The community actively monitors our GitHub Discussions page. Please search for existing threads before starting a new one. Refrain from opening issues on the bug tracker if you're just starting out or if you're not sure if something is a bug in the library code.
Alternatively, join the #ebpf-go channel on Slack if you have other questions regarding the project. Note that this channel is ephemeral and has its history erased past a certain point, which is less helpful for others running into the same problem later.
Packages
This library includes the following packages:
- asm contains a basic assembler, allowing you to write eBPF assembly instructions directly within your Go code. (You don't need to use this if you prefer to write your eBPF program in C.)
- cmd/bpf2go allows compiling and embedding eBPF programs written in C within Go code. As well as compiling the C code, it auto-generates Go code for loading and manipulating the eBPF program and map objects.
- link allows attaching eBPF to various hooks
- perf allows reading from a
PERF_EVENT_ARRAY - ringbuf allows reading from a
BPF_MAP_TYPE_RINGBUFmap - features implements the equivalent
of
bpftool feature probefor discovering BPF-related kernel features using native Go. - rlimit provides a convenient API to lift
the
RLIMIT_MEMLOCKconstraint on kernels before 5.11. - btf allows reading the BPF Type Format.
- pin provides APIs for working with pinned objects on bpffs.
Requirements
- A version of Go that is supported by upstream
- CI is run against kernel.org LTS releases. >= 4.4 should work but EOL'ed versions are not supported.
License
MIT
eBPF Gopher
The eBPF honeygopher is based on the Go gopher designed by Renee French.
# Packages
Package asm is an assembler for eBPF bytecode.
Package btf handles data encoded according to the BPF Type Format.
Package features allows probing for BPF features available to the calling process.
Package link allows attaching eBPF programs to various kernel hooks.
Package perf allows reading from BPF perf event arrays.
Package ringbuf allows interacting with Linux BPF ring buffer.
Package rlimit allows raising RLIMIT_MEMLOCK if necessary for the use of BPF.
# Functions
EnableStats starts the measuring of the runtime and run counts of eBPF programs.
LoadCollection reads an object file and creates and loads its declared resources into the kernel.
LoadCollectionSpec parses an ELF file into a CollectionSpec.
LoadCollectionSpecFromReader parses an ELF file into a CollectionSpec.
LoadPinnedMap opens a Map from a pin (file) on the BPF virtual filesystem.
LoadPinnedProgram loads a Program from a pin (file) on the BPF virtual filesystem.
MapGetNextID returns the ID of the next eBPF map.
MustPossibleCPU is a helper that wraps a call to PossibleCPU and panics if the error is non-nil.
NewCollection creates a Collection from the given spec, creating and loading its declared resources into the kernel.
NewCollectionWithOptions creates a Collection from the given spec using options, creating and loading its declared resources into the kernel.
NewMap creates a new Map.
NewMapFromFD creates a map from a raw fd.
NewMapFromID returns the map for a given id.
NewMapWithOptions creates a new Map.
NewProgram creates a new Program.
NewProgramFromFD creates a program from a raw fd.
NewProgramFromID returns the program for a given id.
NewProgramWithOptions creates a new Program.
PossibleCPU returns the max number of CPUs a system may possibly have Logical CPU numbers must be of the form 0-n.
ProgramGetNextID returns the ID of the next eBPF program.
SanitizeName replaces all invalid characters in name with replacement.
# Constants
Arena - Sparse shared memory region between a BPF program and user space.
Array is an array map.
ArrayOfMaps - Each item in the array is another map.
AttachNone is an alias for AttachCGroupInetIngress for readability reasons.
BloomFilter - Space-efficient data structure to quickly test whether an element exists in a set.
CGroupArray - This is a very niche structure used to help SKBInCGroup determine if an skb is from a socket belonging to a specific cgroup.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
CgroupStorage - Store data keyed on a cgroup.
CGroupStorage - Special map for CGroups.
eBPF program types.
CPUMap - Specialized map to store references to CPUs.
DevMap - Specialized map to store references to network devices.
DevMapHash - Hash-based indexing scheme for references to network devices.
eBPF program types.
eBPF program types.
Hash is a hash map.
HashOfMaps - Each item in the hash map is another map.
InodeStorage - Specialized local storage map for inodes.
eBPF program types.
eBPF program types.
Print verifier state at branch points.
Print verifier state for every instruction.
Print verifier errors and stats at the end of the verification process.
LookupLock look up the value of a spin-locked map.
LPMTrie - This is an implementation of Longest-Prefix-Match Trie structure.
LRUCPUHash - This is NOT like PerCPUHash, this structure is shared among the CPUs, it has more to do with including the CPU id with the LRU calculation so that if a particular CPU is using a value over-and-over again, then it will be saved, but if a value is being retrieved a lot but sparsely across CPUs it is not as important, basically giving weight to CPU locality over overall usage.
LRUHash - This allows you to create a small hash structure that will purge the least recently used items rather than throw an error when you run out of memory.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
PerCPUArray - This data structure is useful for people who have high performance network needs and can reconcile adds at the end of some cycle, so that hashes can be lock free without the use of XAdd, which can be costly.
PerCPUCGroupStorage - Special per CPU map for CGroups.
PerCPUHash - This data structure is useful for people who have high performance network needs and can reconcile adds at the end of some cycle, so that hashes can be lock free without the use of XAdd, which can be costly.
eBPF program types.
PerfEventArray - A perf event array is used in conjunction with PerfEventRead and PerfEventOutput calls, to read the raw bpf_perf_data from the registers.
Pin an object by using its name as the filename.
Valid pin types.
ProgramArray - A program array map is a special kind of array map whose map values contain only file descriptors referring to other eBPF programs.
Queue - FIFO storage for BPF programs.
eBPF program types.
eBPF program types.
ReusePortSockArray - Specialized map to store references to sockets that can be reused.
RingBuf - Similar to PerfEventArray, but shared across all CPUs.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
eBPF program types.
SkStorage - Specialized map for local storage at SK for BPF programs.
eBPF program types.
SockHash - Specialized hash to store references to sockets.
SockMap - Specialized map to store references to sockets.
eBPF program types.
Stack - LIFO storage for BPF programs.
StackTrace - This holds whole user and kernel stack traces, it can be retrieved with GetStackID.
eBPF program types.
StructOpsMap - This map holds a kernel struct with its function pointer implemented in a BPF program.
eBPF program types.
TaskStorage - Specialized local storage map for task_struct.
eBPF program types.
eBPF program types.
All the various map types that can be created.
eBPF program types.
UpdateAny creates a new element or update an existing one.
UpdateExist updates an existing element.
UpdateLock updates elements under bpf_spin_lock.
UpdateNoExist creates a new element.
UserRingbuf - The reverse of RingBuf, used to send messages from user space to BPF programs.
eBPF program types.
XSKMap - Specialized map for XDP programs to store references to open sockets.
# Variables
Errors returned by Map and MapIterator methods.
Errors returned by Map and MapIterator methods.
Errors returned by Map and MapIterator methods.
Errors returned by Map and MapIterator methods.
ErrNotSupported is returned whenever the kernel doesn't support a feature.
# Structs
BatchOptions batch map operations options
Mirrors libbpf struct bpf_map_batch_opts Currently BPF_F_FLAG is the only supported flag (for ElemFlags).
Collection is a collection of live BPF resources present in the kernel.
CollectionOptions control loading a collection into the kernel.
CollectionSpec describes a collection.
LoadPinOptions control how a pinned object is loaded.
Map represents a Map file descriptor.
MapBatchCursor represents a starting point for a batch operation.
MapInfo describes a map.
MapIterator iterates a Map.
MapKV is used to initialize the contents of a Map.
MapOptions control loading a map into the kernel.
MapSpec defines a Map.
Memory implements accessing a Map's memory without making any syscalls.
MissingConstantsError is returned by [CollectionSpec.RewriteConstants].
Program represents BPF program loaded into the kernel.
ProgramInfo describes a program.
ProgramOptions control loading a program into the kernel.
ProgramSpec defines a Program.
Various options for Run'ing a Program.
Variable is a convenience wrapper for modifying global variables of a Collection after loading it into the kernel.
VariableSpec is a convenience wrapper for modifying global variables of a CollectionSpec before loading it into the kernel.
# Type aliases
AttachFlags of the eBPF program used in BPF_PROG_ATTACH command.
AttachType of the eBPF program, needed to differentiate allowed context accesses in some newer program types like CGroupSockAddr.
LogLevel controls the verbosity of the kernel's eBPF program verifier.
MapID represents the unique ID of an eBPF map.
MapLookupFlags controls the behaviour of the map lookup calls.
MapType indicates the type map structure that will be initialized in the kernel.
MapUpdateFlags controls the behaviour of the Map.Update call.
PinType determines whether a map is pinned into a BPFFS.
ProgramID represents the unique ID of an eBPF program.
ProgramType of the eBPF program.
VerifierError is returned by [NewProgram] and [NewProgramWithOptions] if a program is rejected by the verifier.