# README
eBPF
eBPF 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.
The library is maintained by Cloudflare and Cilium.
See ebpf.io for other projects from the eBPF ecosystem.
Getting Started
A small collection of Go and eBPF programs that serve as examples for building your own tools can be found under examples/.
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
Please join the #ebpf-go channel on Slack if you have questions regarding the library.
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.
Requirements
- A version of Go that is supported by upstream
- Linux >= 4.9. CI is run against kernel.org LTS releases. 4.4 should work but is not tested against.
Regenerating Testdata
Run make in the root of this repository to rebuild testdata in all
subpackages. This requires Docker, as it relies on a standardized build
environment to keep the build output stable.
It is possible to regenerate data using Podman by overriding the CONTAINER_*
variables: CONTAINER_ENGINE=podman CONTAINER_RUN_ARGS= make.
The toolchain image build files are kept in testdata/docker/.
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.
No description provided by the author
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 interacting with Linux perf_events.
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 loads a Map from a BPF file.
LoadPinnedProgram loads a Program from a BPF file.
MapGetNextID returns the ID of the next eBPF map.
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.
ProgramGetNextID returns the ID of the next eBPF program.
SanitizeName replaces all invalid characters in name with replacement.
# Constants
Array is an array map.
ArrayOfMaps - Each item in the array is another map.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
AttachNone is an alias for AttachCGroupInetIngress for readability reasons.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
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 - Special map for CGroups.
eBPF program types.
CPUMap - Specialized map to store references to CPUs.
DefaultVerifierLogSize is the default number of bytes allocated for the verifier log.
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.
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 thow an error when you run out of memory.
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.
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 Programs and Maps associated with their symbols.
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.
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.
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.
# 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.
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.
No description provided by the author