cilium/ebpf v0.21.0: Struct Ops, Weak Symbols and BTF deduplication

release · Mar 5, 2026

Hi, everyone! The Cilium project is proud to announce v0.21.0 of ebpf-go, our first major 2026 feature release. Please note that this version comes with a few breaking changes for XDP users that may require some intervention based on your use case, so please read the following section carefully before upgrading! We’ve also removed some long-deprecated APIs.

Breaking changes

XDP Attach Type

This release saw a change to the ELF parsing logic, specifically to XDP programs. Previously, XDP programs had their ProgramSpec.AttachType set to AttachNone. Prompted by upstream changes in Linux 6.18, XDP programs now come with an AttachXDP attach type. This change ensures compatibility with kernels going forward, as well as better interoperability with libbpf-based tools using shared PROG_ARRAY maps.

tl;dr: Linux 6.18 and later disallows mixing attach types within the same program array.

If your application uses a pinned program array, you may need to manually change the attach type of your XDP programs to AttachNone before they are loaded to ensure they can still be inserted into maps containing pre-upgrade programs.

The same goes for BPF links. If you’re updating an XDP link created by an older version of ebpf-go, you need to ensure your XDP program is loaded with the same attach type the link was initially created with, or updating will fail with EINVAL.

For an example of how to deal with this change, here’s the the Cilium PR that implemented logic to try both attach types when updating links.

Windows helper function rename

ebpf-for-windows was upgraded from 0.21.0 to v1.0.0-rc1. efW made breaking changes to the names of helper functions, our API has been updated to match:

New Features

Struct ops — The ELF reader can now parse struct ops sections, building MapSpecs and resolving function-pointer members. link.AttachStructOps has been added to allow attaching a StructOpsMap as a link. A sched_ext example can be found here.
Weak symbol & ELF linking — Programs and maps defined as weak symbols are now fully supported. The ELF reader performs per-symbol decoding for both ProgramSpec and MapSpec, meaning linked objects (produced via bpftool gen object) are now handled correctly.
BTF type deduplication — btf.Builder can now deduplicate types while generating a BTF blob. Deduplication can be enabled by passing BuilderOptions to NewBuilder with the Deduplication field set to true.
ProgramSpec.Compatible was added — ProgramSpec.Tag is now deprecated. The new ProgramSpec.Compatible method compares a loaded program’s tag against both SHA-1 and SHA-256 hashes of the spec, ensuring correct behaviour across kernels — including kernel v6.18+, which switched to SHA-256 for program hashing.
ProgramInfo improvements — The program name as reported by ProgramInfo.Name is now sourced from BTF func info when available to provide the full program name if it’s longer than 15 bytes.
LinkInfo improvements — Added a number of methods and types related to reading back link info.
Reverse symbol lookup — Added Executable.Symbol to resolve addresses to a symbol and relative offset.
Uprobe/kprobe link feature probing — HaveBPFLinkKprobeMulti, HaveBPFLinkUprobeMulti, and HaveBPFLinkKprobeSession are now exported from the features package, making it easier to probe for multi-attach support before loading programs.
Program run batching — A new RunOptions.BatchSize option has been added to support batching when running programs.

Bug Fixes

Allow weak kfuncs loading without CAP_SYS_ADMIN — Loading programs with weak kfuncs on kernels that don’t have the kfunc no longer fails with “operation not permitted” when the caller lacks CAP_SYS_ADMIN. The permission error is now treated as “not found” for weak kfuncs.
ELF reader nil panic — Fixed a panic that could occur when loading an ELF without BTF due to a nil extInfo pointer. Along with the fix, a suite of regression tests was added that exercises the core loader logic with non-BTF ELFs as well.
QueryResult.HaveLinkInfo heuristic — The heuristic has been updated to check for at least one attached program with a non-zero link ID, fixing a false positive introduced by a kernel change that began populating the revision field for cgroup queries.
Windows map/program count — Increased the default map and program count on Windows to reduce failures when loading collections with more maps than previously allocated.

More breaking changes

Deprecations

In this release we have removed a number of features which had been deprecated for a while.

CollectionSpec.RewriteMaps - Pass CollectionOptions.MapReplacements when loading the Collection instead.
CollectionSpec.RewriteConstants - Use CollectionSpec.Variables instead.
NewLinkFromFD - Use NewFromFD instead.
HaveProgType - Use HaveProgramType instead.
IsUnreferencedSymbol - Use errors.Is(err, asm.ErrUnreferencedSymbol) instead.
Instruction.RewriteMapPtr - Use Instruction.AssociateMap instead. If you cannot provide a Map, wrap an fd in a type implementing FDer.
Instruction.Sym - Use Instruction.WithSymbol instead.
Instruction.MapPtr - Use Instruction.Map instead.

Breaking changes to Memory, Variable and VariableSpec

Memory.Size now returns an uint32 instead of an int
Variable.Size now returns an uint32 instead of an uint64
VariableSpec.MapName has been removed, use VariableSpec.SectionName instead.
VariableSpec.Offset is no longer a method, and is now a field.
VariableSpec.Size now returns an uint32 instead of a uint64.
VariableSpec.Type is no longer a method, and is now a field.

Breaking changes to link info

KprobeInfo.Address has been changed from a method into a field.
KprobeInfo.Missed has been changed from a method into a field.
KprobeMultiInfo.AddressCount has been removed, use len(KprobeMultiInfo.Address) instead.
KprobeMultiInfo.Flags has been changed from a method into a field.
KprobeMultiInfo.Missed has been changed from a method into a field.
NetNsInfo.NetnsIno was renamed to NetNsInfo.NetnsInode
NetfilterInfo.Hooknum has been renamed to NetfilterInfo.Hook and changed from an uint32 to a NetfilterInetHook
NetfilterInfo.Pf has been renamed to NetfilterInfo.ProtocolFamily and changed from an uint32 to a NetfilterProtocolFamily
TracingInfo.TargetObjId has been renamed to NetfilterInfo.TargetObjectId

Breaking changes to BTF API

We exported methods and types from the btf package. This allowed us to directly assign BTF func info, line info and CO-RE relocations to instructions from outside of the btf package, making some methods unneeded and thus got removed.

ExtInfos.Assign has been removed, use WithFuncMetadata, Instruction.WithSource, and WithCORERelocationMetadata instead.
AssignMetadataToInstructions has been removed, use WithFuncMetadata, Instruction.WithSource, and WithCORERelocationMetadata instead.
CORERelocationInfos was renamed to CORERelocationOffsets.
NewBuilder now takes an additional BuilderOptions. This can be left nil.

What’s Changed

elf_reader: add struct_ops support by @shun159 in https://github.com/cilium/ebpf/pull/1869
link: use PlatformPrefix in TestKprobeMultiProgramCall by @lmb in https://github.com/cilium/ebpf/pull/1890
link: change QueryResult.HaveLinkInfo heuristic by @ti-mo in https://github.com/cilium/ebpf/pull/1892
link: add StructOpsMap support by @shun159 in https://github.com/cilium/ebpf/pull/1844
windows: Increase default map count in call to ebpf_object_load_native_by_fds by @ExceptionalHandler in https://github.com/cilium/ebpf/pull/1887
examples: Add a minimal sched_ext example by @shun159 in https://github.com/cilium/ebpf/pull/1895
ci: use tagged efW releases by @lmb in https://github.com/cilium/ebpf/pull/1899
feat: read full program name from function info by @secDre4mer in https://github.com/cilium/ebpf/pull/1889
Improve handling of external dependencies by @lmb in https://github.com/cilium/ebpf/pull/1897
examples: Do not override imported namespace with variable by @isodude in https://github.com/cilium/ebpf/pull/1901
Add codeowner for windows specific code by @lmb in https://github.com/cilium/ebpf/pull/1893
fix: splitting the modification and the return statement by @yrpang in https://github.com/cilium/ebpf/pull/1909
features: export link features by @ajwerner in https://github.com/cilium/ebpf/pull/1906
Deprecate All The Things by @ti-mo in https://github.com/cilium/ebpf/pull/1894
deps: use github.com mirror of linux-stable by @lmb in https://github.com/cilium/ebpf/pull/1912
ci: update efW to 1.0.0-rc2 by @lmb in https://github.com/cilium/ebpf/pull/1911
Allow callers to create VariableSpecs by @lmb in https://github.com/cilium/ebpf/pull/1882
feat: support program run batching with new BatchSize option by @takehaya in https://github.com/cilium/ebpf/pull/1914
btf/testdata: Update vmlinux and btf_testmod to latest by @dylandreimerink in https://github.com/cilium/ebpf/pull/1928
test: Separate the netns for netkitanchor by @Jack-R-lantern in https://github.com/cilium/ebpf/pull/1913
Update CI kernel to v6.18 and fix tests by @dylandreimerink in https://github.com/cilium/ebpf/pull/1933
Deprecate ProgramSpec.Tag, and introduce ProgramSpec.Compatible by @dylandreimerink in https://github.com/cilium/ebpf/pull/1932
fix(elf): set attach_type to BPF_XDP for XDP section by @chantra in https://github.com/cilium/ebpf/pull/1919
elf: drop legacy non-libbpf xdp* and seccomp attach types by @ti-mo in https://github.com/cilium/ebpf/pull/1934
btf: Add type deduplication by @dylandreimerink in https://github.com/cilium/ebpf/pull/1903
uprobe: only verify ELF if required by @RonFed in https://github.com/cilium/ebpf/pull/1938
ringbuf: add poller and eventRing interfaces by @HueCodes in https://github.com/cilium/ebpf/pull/1945
feat: more link inspection support by @secDre4mer in https://github.com/cilium/ebpf/pull/1896
btf/testdata: Update vmlinux blob by @dylandreimerink in https://github.com/cilium/ebpf/pull/1954
Support BPF object linking by @dylandreimerink in https://github.com/cilium/ebpf/pull/1942
elf_reader: add tests for ELF objects without BTF by @puwun in https://github.com/cilium/ebpf/pull/1939
Allow loading weak kfuncs without CAP_SYS_ADMIN by @dylandreimerink in https://github.com/cilium/ebpf/pull/1950

New Contributors

@ExceptionalHandler made their first contribution in https://github.com/cilium/ebpf/pull/1887
@secDre4mer made their first contribution in https://github.com/cilium/ebpf/pull/1889
@isodude made their first contribution in https://github.com/cilium/ebpf/pull/1901
@yrpang made their first contribution in https://github.com/cilium/ebpf/pull/1909
@ajwerner made their first contribution in https://github.com/cilium/ebpf/pull/1906
@takehaya made their first contribution in https://github.com/cilium/ebpf/pull/1914
@Jack-R-lantern made their first contribution in https://github.com/cilium/ebpf/pull/1913
@chantra made their first contribution in https://github.com/cilium/ebpf/pull/1919
@HueCodes made their first contribution in https://github.com/cilium/ebpf/pull/1945
@puwun made their first contribution in https://github.com/cilium/ebpf/pull/1939

Full Changelog: https://github.com/cilium/ebpf/compare/v0.20.0...v0.21.0

View source